<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
<title>Robot Framework User Guide</title>
<style type="text/css">

/* Robot Framework User Guide Style Sheet

   This stylesheet contains styles from restructuredText's default 
   'html4css1.css' and after that modifications needed for Robot Framework User
   Guide. These styles are added into the same file against suggestions at 
   reST's stylesheet HowTo mentioned below, because we want to be able to
   embed all styles into the created HTML file. Everything before 'Robot 
   Framework User Guide Modifications' text is from 'html4css1.css' without 
   any changes so that part can still be changed easily.
*/


/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }


/* **************************************** *
 * Robot Framework User Guide Modifications * 
 * **************************************** */

/* Tables
   - example, tsv-example: test data examples
   - messages: log message examples
   - tabular: normal tabular information
*/
table.example, table.tsv-example, table.messages, table.tabular {
    border: 1px solid #808080;
    border-collapse: collapse;
    empty-cell: show;
    margin: 0.5em 2em;
}
table.example caption, table.tsv-example caption, table.tabular caption {
    text-align: left;
    padding-bottom: 0.5em;
    font-style: italic;
    font-size: 0.9em;
    width: 100%;
}
table.example th, table.example td, table.tsv-example td {
    border: 1px solid #808080;
    font-family: arial,helvetica,sans-serif;
    height: 1.2em;
    font-size: 0.8em;
}
table.example th {
    padding: 0.1em 1em;
    background: #E0E0E0;
}
table.example td, table.tsv-example td {
    padding: 0.1em 1em 0.1em 0.3em;
}
table.tabular th, table.tabular td {
    border: 1px solid black;
    padding: 0.1em 0.3em;
    height: 1.2em;
    font-size: 0.8em;
}
table.messages {
    border: 1px solid gray;
    font-family: monospace;
    margin: 1em 2em;
    width: 60%;
}
table.messages td {
    vertical-align: top;
    padding: 0.1em 0.2em;
}
table.messages td.time {
    width: 7em;
    letter-spacing: -0.05em;
} 
table.messages td.level {
    width: 5em;
    text-align: center;
}
table.messages td.fail, table.messages td.error {
    color: red;
}
table.messages td.pass {
    color: #009900;
}
table.messages td.warn {
    color: #FFCC00;
}

/* Roles -- these are defined in roles.txt file */

.var {
    background: #f4f4f4;
    font-size: 0.9em;
}
.opt {
    font-style: italic;
}
.prog, .code, .cli {
    background: #f4f4f4;
    font-family: monospace;
}
.msg {
    font-family: monospace;
}
.name {  
    font-style: italic;
}
.path {
    font-style: italic;
}
.misc, .literal {
    background: #f4f4f4;
}


/* Overridden and modified styles */

cite {
    font-size: 0.95em;
}
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
    border: 1px solid gray;
    margin: 1em 2em;
    padding: 0.7em 1em;
    font-size: 0.9em;
}
pre.literal-block, pre.doctest-block {
    background: #f4f4f4;
}
li, li p.first {
    margin-top: 0.3em;
    margin-bottom: 0.3em;
}
div.contents li {
    margin-top: 0em;
    margin-bottom: 0em;
}
a img {
    border: 1px solid blue;
}

/* Pygments 

- Styles generated using "HtmlFormatter().get_style_defs('.highlight')"
- Changed only background (f8f8f8 -> f4f4f4) and added margin
- For more details see e.g. http://pygments.org/docs/quickstart/
*/

.highlight  { background: #f4f4f4; margin: 1em 2em; }
.highlight .c { color: #408080; font-style: italic } /* Comment */
.highlight .err { border: 1px solid #FF0000 } /* Error */
.highlight .k { color: #008000; font-weight: bold } /* Keyword */
.highlight .o { color: #666666 } /* Operator */
.highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #BC7A00 } /* Comment.Preproc */
.highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */
.highlight .cs { color: #408080; font-style: italic } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
.highlight .go { color: #808080 } /* Generic.Output */
.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #0040D0 } /* Generic.Traceback */
.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
.highlight .kp { color: #008000 } /* Keyword.Pseudo */
.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #B00040 } /* Keyword.Type */
.highlight .m { color: #666666 } /* Literal.Number */
.highlight .s { color: #BA2121 } /* Literal.String */
.highlight .na { color: #7D9029 } /* Name.Attribute */
.highlight .nb { color: #008000 } /* Name.Builtin */
.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */
.highlight .no { color: #880000 } /* Name.Constant */
.highlight .nd { color: #AA22FF } /* Name.Decorator */
.highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */
.highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0000FF } /* Name.Function */
.highlight .nl { color: #A0A000 } /* Name.Label */
.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #19177C } /* Name.Variable */
.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mf { color: #666666 } /* Literal.Number.Float */
.highlight .mh { color: #666666 } /* Literal.Number.Hex */
.highlight .mi { color: #666666 } /* Literal.Number.Integer */
.highlight .mo { color: #666666 } /* Literal.Number.Oct */
.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
.highlight .sc { color: #BA2121 } /* Literal.String.Char */
.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
.highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
.highlight .sx { color: #008000 } /* Literal.String.Other */
.highlight .sr { color: #BB6688 } /* Literal.String.Regex */
.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
.highlight .ss { color: #19177C } /* Literal.String.Symbol */
.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
.highlight .vc { color: #19177C } /* Name.Variable.Class */
.highlight .vg { color: #19177C } /* Name.Variable.Global */
.highlight .vi { color: #19177C } /* Name.Variable.Instance */
.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */

</style>
</head>
<body>
<div class="document" id="robot-framework-user-guide">
<h1 class="title">Robot Framework User Guide</h1>
<h2 class="subtitle" id="version-version">Version trunk 20120202</h2>

<!-- This data file has been placed in the public domain. -->
<!-- Derived from the Unicode character mappings available from
<http://www.w3.org/2003/entities/xml/>.
Processed by unicode2rstsubs.py, part of Docutils:
<http://docutils.sourceforge.net>. -->
<!-- Roles to use in text like :rolename:`text`. Styled in userguide.css.
- var    variables
- opt    settings in setting table (e.g. Force Tags), tc/kw tables
         (e.g [Documentation]) and command line options (e.g. - -name)
- prog   program names (e.g. rebot, risto.py)
- code   programming code
- msg    test case status and message, as well as log messages and levels
- name   keyword, library, test case, test suite, etc. names
- cli    command line examples (note that options alone use opt)
- path   file names and paths
- misc   everything else (synonym to ``text``) -->
<div class="line-block">
<div class="line">Copyright © Nokia Siemens Networks 2008-2011</div>
<div class="line">Licensed under the <a class="reference external" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported</a> license</div>
</div>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#getting-started" id="id256">1&nbsp;&nbsp;&nbsp;Getting started</a><ul class="auto-toc">
<li><a class="reference internal" href="#introduction" id="id257">1.1&nbsp;&nbsp;&nbsp;Introduction</a></li>
<li><a class="reference internal" href="#copyright-and-license" id="id258">1.2&nbsp;&nbsp;&nbsp;Copyright and license</a></li>
<li><a class="reference internal" href="#installation-and-uninstallation" id="id259">1.3&nbsp;&nbsp;&nbsp;Installation and uninstallation</a></li>
<li><a class="reference internal" href="#demonstrations" id="id260">1.4&nbsp;&nbsp;&nbsp;Demonstrations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#creating-test-data" id="id261">2&nbsp;&nbsp;&nbsp;Creating test data</a><ul class="auto-toc">
<li><a class="reference internal" href="#test-data-syntax" id="id262">2.1&nbsp;&nbsp;&nbsp;Test data syntax</a></li>
<li><a class="reference internal" href="#creating-test-cases" id="id263">2.2&nbsp;&nbsp;&nbsp;Creating test cases</a></li>
<li><a class="reference internal" href="#creating-test-suites" id="id264">2.3&nbsp;&nbsp;&nbsp;Creating test suites</a></li>
<li><a class="reference internal" href="#using-test-libraries" id="id265">2.4&nbsp;&nbsp;&nbsp;Using test libraries</a></li>
<li><a class="reference internal" href="#variables" id="id266">2.5&nbsp;&nbsp;&nbsp;Variables</a></li>
<li><a class="reference internal" href="#creating-user-keywords" id="id267">2.6&nbsp;&nbsp;&nbsp;Creating user keywords</a></li>
<li><a class="reference internal" href="#resource-and-variable-files" id="id268">2.7&nbsp;&nbsp;&nbsp;Resource and variable files</a></li>
<li><a class="reference internal" href="#advanced-features" id="id269">2.8&nbsp;&nbsp;&nbsp;Advanced features</a></li>
</ul>
</li>
<li><a class="reference internal" href="#executing-test-cases" id="id270">3&nbsp;&nbsp;&nbsp;Executing test cases</a><ul class="auto-toc">
<li><a class="reference internal" href="#basic-usage" id="id271">3.1&nbsp;&nbsp;&nbsp;Basic usage</a></li>
<li><a class="reference internal" href="#test-execution" id="id272">3.2&nbsp;&nbsp;&nbsp;Test execution</a></li>
<li><a class="reference internal" href="#post-processing-outputs" id="id273">3.3&nbsp;&nbsp;&nbsp;Post-processing outputs</a></li>
<li><a class="reference internal" href="#configuring-execution" id="id274">3.4&nbsp;&nbsp;&nbsp;Configuring execution</a></li>
<li><a class="reference internal" href="#created-outputs" id="id275">3.5&nbsp;&nbsp;&nbsp;Created outputs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extending-robot-framework" id="id276">4&nbsp;&nbsp;&nbsp;Extending Robot Framework</a><ul class="auto-toc">
<li><a class="reference internal" href="#creating-test-libraries" id="id277">4.1&nbsp;&nbsp;&nbsp;Creating test libraries</a></li>
<li><a class="reference internal" href="#remote-library-interface" id="id278">4.2&nbsp;&nbsp;&nbsp;Remote library interface</a></li>
<li><a class="reference internal" href="#using-listener-interface" id="id279">4.3&nbsp;&nbsp;&nbsp;Using listener interface</a></li>
<li><a class="reference internal" href="#using-internal-apis" id="id280">4.4&nbsp;&nbsp;&nbsp;Using internal APIs</a></li>
<li><a class="reference internal" href="#using-robot-framework-from-java" id="id281">4.5&nbsp;&nbsp;&nbsp;Using Robot Framework from Java</a></li>
</ul>
</li>
<li><a class="reference internal" href="#supporting-tools" id="id282">5&nbsp;&nbsp;&nbsp;Supporting Tools</a><ul class="auto-toc">
<li><a class="reference internal" href="#library-documentation-tool-libdoc" id="id283">5.1&nbsp;&nbsp;&nbsp;Library documentation tool (<span class="prog">libdoc</span>)</a></li>
<li><a class="reference internal" href="#test-data-clean-up-tool-tidy" id="id284">5.2&nbsp;&nbsp;&nbsp;Test data clean-up tool (<span class="prog">tidy</span>)</a></li>
<li><a class="reference internal" href="#test-data-editing-tool-ride" id="id285">5.3&nbsp;&nbsp;&nbsp;Test data editing tool (RIDE)</a></li>
<li><a class="reference internal" href="#other-tools" id="id286">5.4&nbsp;&nbsp;&nbsp;Other tools</a></li>
</ul>
</li>
<li><a class="reference internal" href="#appendices" id="id287">6&nbsp;&nbsp;&nbsp;Appendices</a><ul class="auto-toc">
<li><a class="reference internal" href="#all-available-settings-in-test-data" id="id288">6.1&nbsp;&nbsp;&nbsp;All available settings in test data</a></li>
<li><a class="reference internal" href="#all-command-line-options" id="id289">6.2&nbsp;&nbsp;&nbsp;All command line options</a></li>
<li><a class="reference internal" href="#test-data-templates" id="id290">6.3&nbsp;&nbsp;&nbsp;Test data templates</a></li>
<li><a class="reference internal" href="#documentation-formatting" id="id291">6.4&nbsp;&nbsp;&nbsp;Documentation formatting</a></li>
<li><a class="reference internal" href="#time-format" id="id292">6.5&nbsp;&nbsp;&nbsp;Time format</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="getting-started">
<h1><a class="toc-backref" href="#id256">1&nbsp;&nbsp;&nbsp;Getting started</a></h1>
<div class="contents local topic" id="contents">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#introduction" id="id293">1.1&nbsp;&nbsp;&nbsp;Introduction</a></li>
<li><a class="reference internal" href="#copyright-and-license" id="id294">1.2&nbsp;&nbsp;&nbsp;Copyright and license</a></li>
<li><a class="reference internal" href="#installation-and-uninstallation" id="id295">1.3&nbsp;&nbsp;&nbsp;Installation and uninstallation</a></li>
<li><a class="reference internal" href="#demonstrations" id="id296">1.4&nbsp;&nbsp;&nbsp;Demonstrations</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id293">1.1&nbsp;&nbsp;&nbsp;Introduction</a></h2>
<p>Robot Framework is a Python-based, extensible keyword-driven test
automation framework for end-to-end acceptance testing and
acceptance-test-driven development (ATDD). It can be used for testing
distributed, heterogeneous applications, where verification requires
touching several technologies and interfaces.</p>
<div class="contents local topic" id="id2">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#why-robot-framework" id="id297">1.1.1&nbsp;&nbsp;&nbsp;Why Robot Framework?</a></li>
<li><a class="reference internal" href="#high-level-architecture" id="id298">1.1.2&nbsp;&nbsp;&nbsp;High-level architecture</a></li>
<li><a class="reference internal" href="#screenshots" id="id299">1.1.3&nbsp;&nbsp;&nbsp;Screenshots</a></li>
<li><a class="reference internal" href="#getting-more-information" id="id300">1.1.4&nbsp;&nbsp;&nbsp;Getting more information</a><ul>
<li><a class="reference internal" href="#project-pages" id="id301">Project pages</a></li>
<li><a class="reference internal" href="#mailing-lists" id="id302">Mailing lists</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="why-robot-framework">
<h3><a class="toc-backref" href="#id297">1.1.1&nbsp;&nbsp;&nbsp;Why Robot Framework?</a></h3>
<ul class="simple">
<li>Enables easy-to-use tabular syntax for <a class="reference internal" href="#creating-test-cases">creating test cases</a> in a uniform
way.</li>
<li>Provides ability to create reusable <a class="reference internal" href="#creating-user-keywords">higher-level keywords</a> from the
existing keywords.</li>
<li>Provides easy-to-read result <a class="reference internal" href="#report-file">reports</a> and <a class="reference internal" href="#log-file">logs</a> in HTML format.</li>
<li>Is platform and application independent.</li>
<li>Provides a simple <a class="reference internal" href="#creating-test-libraries">library API</a> for creating customized test libraries
which can be implemented natively with either Python or Java.</li>
<li>Provides a <a class="reference internal" href="#executing-test-cases">command line interface</a> and XML based <a class="reference internal" href="#output-file">output files</a>  for
integration into existing build infrastructure (continuous integration
systems).</li>
<li>Provides support for Selenium for web testing, Java GUI testing, running
processes, Telnet, SSH, and so on.</li>
<li>Supports creating <a class="reference internal" href="#data-driven-style">data-driven test cases</a>.</li>
<li>Has built-in support for <a class="reference internal" href="#variables">variables</a>, practical particularly for testing in
different environments.</li>
<li>Provides <a class="reference internal" href="#tagging-test-cases">tagging</a> to categorize and <a class="reference internal" href="#selecting-test-cases">select test cases</a> to be executed.</li>
<li>Enables easy integration with source control: <a class="reference internal" href="#creating-test-suites">test suites</a> are just files
and directories that can be versioned with the production code.</li>
<li>Provides <a class="reference internal" href="#test-setup-and-teardown">test-case</a> and <a class="reference internal" href="#suite-setup-and-teardown">test-suite</a> -level setup and teardown.</li>
<li>The modular architecture supports creating tests even for applications with
several diverse interfaces.</li>
</ul>
</div>
<div class="section" id="high-level-architecture">
<h3><a class="toc-backref" href="#id298">1.1.2&nbsp;&nbsp;&nbsp;High-level architecture</a></h3>
<p>Robot Framework is a generic, application and technology independent
framework. It has a highly modular architecture illustrated in the
diagram below.</p>
<div class="figure">
<img alt="src/GettingStarted/architecture.png" src="src/GettingStarted/architecture.png" />
<p class="caption">Robot Framework architecture</p>
</div>
<p>The <a class="reference internal" href="#creating-test-data">test data</a> is in simple, easy-to-edit tabular format. When
Robot Framework is started, it processes the test data, <a class="reference internal" href="#executing-test-cases">executes test
cases</a> and generates logs and reports. The core framework does not
know anything about the target under test, and the interaction with it
is handled by <a class="reference internal" href="#creating-test-libraries">test libraries</a>. Libraries can either use application
interfaces directly or use lower level test tools as drivers.</p>
</div>
<div class="section" id="screenshots">
<h3><a class="toc-backref" href="#id299">1.1.3&nbsp;&nbsp;&nbsp;Screenshots</a></h3>
<p>Following screenshots show examples of the <a class="reference internal" href="#creating-test-data">test data</a> and created
<a class="reference internal" href="#report-file">reports</a> and <a class="reference internal" href="#log-file">logs</a>.</p>
<div class="figure">
<img alt="src/GettingStarted/testdata_screenshots.png" src="src/GettingStarted/testdata_screenshots.png" />
<p class="caption">Test case files</p>
</div>
<div class="figure">
<img alt="src/GettingStarted/screenshots.png" src="src/GettingStarted/screenshots.png" />
<p class="caption">Reports and logs</p>
</div>
</div>
<div class="section" id="getting-more-information">
<h3><a class="toc-backref" href="#id300">1.1.4&nbsp;&nbsp;&nbsp;Getting more information</a></h3>
<div class="section" id="project-pages">
<h4><a class="toc-backref" href="#id301">Project pages</a></h4>
<p>The number one place to find more information about Robot Framework
is the project web site at <a class="reference external" href="http://robotframework.org">http://robotframework.org</a>. This User Guide is
naturally available there but you can also find more <a class="reference external" href="http://code.google.com/p/robotframework/wiki/DocumentationIndex">documentation</a>,
an <a class="reference external" href="http://code.google.com/p/robotframework/issues">issue tracker</a>, <a class="reference external" href="http://code.google.com/p/robotframework/downloads">downloads</a>, <a class="reference external" href="http://code.google.com/p/robotframework/source">source code</a> and links to other
related projects. Robot Framework is hosted on <a class="reference external" href="http://code.google.com">Google Code</a> which
provides excellent free services for open source projects.</p>
</div>
<div class="section" id="mailing-lists">
<h4><a class="toc-backref" href="#id302">Mailing lists</a></h4>
<p>There are several Robot Framework mailing lists where to ask and
search for more information. The mailing list archives are open for
everyone (including the search engines) and everyone can also join
these lists freely. Only list members can send mails, though, and to
prevent spam new users are moderated which means that it might take a
little time before your first message goes through.  Do not be afraid
to send question to mailing lists but remember <a class="reference external" href="http://www.catb.org/~esr/faqs/smart-questions.html">How To Ask Questions
The Smart Way</a>.</p>
<dl class="docutils">
<dt><a class="reference external" href="http://groups.google.com/group/robotframework-users">robotframework-users</a></dt>
<dd>General discussion about all Robot Framework related
issues. Questions and problems can be sent to this list. Used also
for information sharing for all users.</dd>
<dt><a class="reference external" href="http://groups.google.com/group/robotframework-announce">robotframework-announce</a></dt>
<dd>An announcements-only mailing list where only moderators can send
messages. All announcements are sent also to the
robotframework-users mailing list so there is no need to join both
lists.</dd>
<dt><a class="reference external" href="http://groups.google.com/group/robotframework-devel">robotframework-devel</a></dt>
<dd>Discussion about Robot Framework development.</dd>
<dt><a class="reference external" href="http://groups.google.com/group/robotframework-commit">robotframework-commit</a></dt>
<dd>Automatically generated mails about commits to the version control
system, build results, new and edited issues, and so on. Can be used to
follow Robot Framework development.</dd>
</dl>
</div>
</div>
</div>
<div class="section" id="copyright-and-license">
<h2><a class="toc-backref" href="#id294">1.2&nbsp;&nbsp;&nbsp;Copyright and license</a></h2>
<p>Robot Framework itself, test libraries and supporting tools distributed with it,
as well as this user guide and other provided documentation have the following
copyright statement.</p>
<pre class="literal-block">
Copyright 2008-2011 Nokia Siemens Networks Oyj

Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an &quot;AS IS&quot; BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

</pre>
</div>
<div class="section" id="installation-and-uninstallation">
<h2><a class="toc-backref" href="#id295">1.3&nbsp;&nbsp;&nbsp;Installation and uninstallation</a></h2>
<div class="contents local topic" id="id21">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#id22" id="id303">1.3.1&nbsp;&nbsp;&nbsp;Introduction</a></li>
<li><a class="reference internal" href="#preconditions" id="id304">1.3.2&nbsp;&nbsp;&nbsp;Preconditions</a><ul>
<li><a class="reference internal" href="#python-installation" id="id305">Python installation</a></li>
<li><a class="reference internal" href="#jython-installation" id="id306">Jython installation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installation" id="id307">1.3.3&nbsp;&nbsp;&nbsp;Installation</a><ul>
<li><a class="reference internal" href="#installing-from-source" id="id308">Installing from source</a></li>
<li><a class="reference internal" href="#using-windows-installer" id="id309">Using Windows installer</a></li>
<li><a class="reference internal" href="#using-easy-install" id="id310">Using Easy Install</a></li>
<li><a class="reference internal" href="#using-one-click-installer" id="id311">Using One Click Installer</a></li>
<li><a class="reference internal" href="#manual-installation" id="id312">Manual installation</a></li>
<li><a class="reference internal" href="#standalone-jar-distribution" id="id313">Standalone jar distribution</a></li>
<li><a class="reference internal" href="#where-files-are-installed" id="id314">Where files are installed</a></li>
<li><a class="reference internal" href="#setting-up-environment" id="id315">Setting up environment</a></li>
<li><a class="reference internal" href="#verifying-installation" id="id316">Verifying installation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#uninstallation" id="id317">1.3.4&nbsp;&nbsp;&nbsp;Uninstallation</a></li>
<li><a class="reference internal" href="#upgrading" id="id318">1.3.5&nbsp;&nbsp;&nbsp;Upgrading</a></li>
</ul>
</div>
<div class="section" id="id22">
<h3><a class="toc-backref" href="#id303">1.3.1&nbsp;&nbsp;&nbsp;Introduction</a></h3>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The installation system was changed quite a bit for
Robot Framework 2.7. The instructions below are correct
only for version 2.6 and older. The new installation procedure
is described in the project <a class="reference external" href="http://code.google.com/p/robotframework/wiki/NewInstallation">Wiki pages</a>. The user guide
will be updated before the final release.</p>
</div>
<p>There are several ways to install Robot Framework:</p>
<dl class="docutils">
<dt><a class="reference internal" href="#installing-from-source">Installing from source</a></dt>
<dd>You can get the source code either as a source distribution
package or directly from version control system. In the former
case, first extract the package somewhere, and as a result, you
have a directory named <tt class="docutils literal"><span class="pre">robotframework-&lt;version&gt;</span></tt>. Detailed
instructions follow, but in short, what you need to do is to go to
the created directory and run the <tt class="docutils literal">python setup.py install</tt>
command.</dd>
<dt><a class="reference internal" href="#using-windows-installer">Using Windows installer</a></dt>
<dd>There is a special graphical installer for Windows operating system.</dd>
<dt><a class="reference internal" href="#using-easy-install">Using Easy Install</a></dt>
<dd>If Python package managing tool <a class="reference external" href="http://peak.telecommunity.com/DevCenter/EasyInstall">Easy Install</a> is available, installing
Robot Framework is as easy as running command
<span class="cli">easy_install robotframework</span>.</dd>
<dt><a class="reference internal" href="#using-one-click-installer">Using One Click Installer</a></dt>
<dd>If you are using Windows XP and you do not have preconditions (<a class="reference external" href="http://www.python.org/">Python</a> and
optional <a class="reference external" href="http://www.jython.org/">Jython</a>) installed, you can use <a class="reference external" href="../../tools/oneclickinstaller/doc/oneclickinstaller.html">One Click Installer</a> to do all
the needed installations.</dd>
<dt><a class="reference internal" href="#standalone-jar-distribution">Standalone jar distribution</a></dt>
<dd>If you need to run tests with only Jython, the easiest way to install everything
is to downloading the standalone <span class="path">robotframework-&lt;version&gt;.jar</span>, which contains
both Jython and Robot Framework.</dd>
</dl>
<p>Installation packages are available from
<a class="reference external" href="http://downloads.robotframework.org">http://downloads.robotframework.org</a>, and source code from
<a class="reference external" href="http://source.robotframework.org">http://source.robotframework.org</a>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">At the momemt it is not possible to install Robot Framework using
<a class="reference external" href="http://www.pip-installer.org">pip</a>. For more information see <a class="reference external" href="http://code.google.com/p/robotframework/issues/detail?id=885">issue 885</a>.</p>
</div>
</div>
<div class="section" id="preconditions">
<h3><a class="toc-backref" href="#id304">1.3.2&nbsp;&nbsp;&nbsp;Preconditions</a></h3>
<p>Robot Framework runs both on <a class="reference external" href="http://www.python.org/">Python</a> and <a class="reference external" href="http://www.jython.org/">Jython</a>, and you need to have at least
one of them to be able to use it. However, some of the provided installers only
work with Python, so installing it is always recommended.</p>
<div class="section" id="python-installation">
<h4><a class="toc-backref" href="#id305">Python installation</a></h4>
<p>Starting from Robot Framework 2.5, Python 2.5 is the minimum supported Python
version.  Earlier versions support Python 2.3 or newer. On most UNIX-like
systems, you have Python installed by default. If you are on Windows or
otherwise need to install Python yourself, your best place to start is probably
the <a class="reference external" href="http://www.python.org/">Python homepage</a>. There you can download a suitable installer and get
more information about the installation and Python in general.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Robot Framework is currently not compatible with Python 3.x versions.
Python 3.0 was intentionally backwards incompatible with earlier
Python releases and Robot Framework has not yet been ported to
support it.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">On Windows, and especially on Windows Vista, it is
recommended to install Python to all users, and to run the
installation as an administrator.</p>
</div>
</div>
<div class="section" id="jython-installation">
<h4><a class="toc-backref" href="#id306">Jython installation</a></h4>
<p>Using test libraries implemented with Java or using Java tools directly
requires running Robot Framework on Jython, which in turn requires Java Runtime
Environment (JRE). Jython 2.5 requires Java 1.5 or newer. Both Oracle/Sun and
IBM Java implementations are supported.</p>
<p>Starting from Robot Framework 2.5, the minimum supported Jython version is 2.5.
Earlier Robot Framework versions support also Jython 2.2.</p>
<p>Installing Jython is a fairly easy procedure, and the first step is getting an
installer from the <a class="reference external" href="http://www.jython.org/">Jython homepage</a>. Note that the installer is an executable
JAR package, which you need to run as <span class="cli">java -jar jython_installer-&lt;version&gt;.jar</span>.
Depending on your system, the installer runs either in graphical or textual
mode, but in both cases, the actual installation procedure is very easy.</p>
<p>There are three ways to install Robot Framework so that it can be run
with Jython.</p>
<ol class="arabic">
<li><p class="first">With all supported Jython versions, it is possible to install Robot
Framework using Python and still start execution using Jython.
When installing Robot Framework with Python, its installer tries to
find the Jython executable on the system to create the
<span class="prog">jybot</span> runner script correctly. Jython is found if:</p>
<ul>
<li><p class="first">Jython can be executed in the system directly (i.e. it is in the
<span class="var">PATH</span>).</p>
</li>
<li><p class="first">An environment variable <span class="var">JYTHON_HOME</span> is set and it points
to the Jython installation directory.</p>
</li>
<li><p class="first">The installer finds the Jython installation directory from the
system. On Windows, it is searched from the <span class="path">C:\</span> and
<span class="path">D:\</span> drives, and on other systems from the
<span class="path">/usr/local</span> and <span class="path">/opt</span> directories. The directory is
found if it is under the searched directories mentioned above, or
one level deeper. For example, the following Jython installation
directories would be found by the installer:</p>
<pre class="literal-block">
C:\APPS\Jython2.5.1
D:\Jython251
/usr/local/jython2.5.1
/opt/whatever/Jython251
</pre>
</li>
</ul>
</li>
<li><p class="first">With Jython 2.5, it is possible to install Robot Framework without
having Python available by <a class="reference internal" href="#installing-from-source">installing from source</a>.</p>
</li>
<li><p class="first">It is possible to do <a class="reference internal" href="#manual-installation">manual installation</a>.</p>
</li>
</ol>
</div>
</div>
<div class="section" id="installation">
<h3><a class="toc-backref" href="#id307">1.3.3&nbsp;&nbsp;&nbsp;Installation</a></h3>
<div class="section" id="installing-from-source">
<h4><a class="toc-backref" href="#id308">Installing from source</a></h4>
<p>You can get Robot Framework source code either directly from version
control or as a source distribution package that needs to be extracted
somewhere. In both cases, you should have a directory containing the
source code, documentation, tools, templates, and so on.</p>
<p>You should be able to install Robot Framework to any environment where
Python runs using a source distribution. The installation is done by
running the following command from the command line in the
extracted directory:</p>
<pre class="literal-block">
python setup.py install
</pre>
<p><span class="prog">setup.py</span> is a standard Python installer script. It can take
several parameters allowing, for example, installation into
non-default locations not requiring administrative rights. It is also
used for creating distribution packages.</p>
<p><span class="prog">install.py</span> is a custom <a class="reference internal" href="#uninstallation">uninstallation</a> script for Robot
Framework. It can also be used for installation, but it simply uses
<span class="prog">setup.py</span>, and thus is totally equivalent to the command above.</p>
<p>It is possible to install Robot Framework 2.5 also using Jython. In
this case the <span class="prog">pybot</span> runner script is not created.</p>
<p>With the installation you get a rather long output, and
something like the following text should appear at the end.
The actual output obviously depends on your environment.</p>
<pre class="literal-block">
Creating Robot Framework runner scripts...
Installation directory: /usr/lib/python2.5/site-packages/robot
Python executable: /usr/bin/python
Jython executable: /cygdrive/c/jython2.5/jython.bat (found from system)
Pybot script: /usr/bin/pybot
Jybot script: /usr/bin/jybot
Rebot script: /usr/bin/rebot
</pre>
</div>
<div class="section" id="using-windows-installer">
<h4><a class="toc-backref" href="#id309">Using Windows installer</a></h4>
<p>There are separate graphical installers for 32 bit (more common) and
64 bit Windows systems. The former installer has name in format
<span class="path">robotframework-&lt;version&gt;.win32.exe</span> and the latter
<span class="path">robotframework-&lt;version&gt;.win-amd64.exe</span>. The installation
itself requires only double clicking the appropriate installer and
following instructions.</p>
<p>After the installation you probably want to <a class="reference internal" href="#setting-up-environment">set the environment</a> so
that Robot Framework runner scripts can be executed easily. Notice
that the framework is automatically installed <a class="reference internal" href="#where-files-are-installed">under the Python
installation</a> and that location cannot be altered at this point.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">With Python 2.6 and 2.7 you need to add the Python installation
directory into <span class="var">PATH</span> environment variable <em>before</em>
running the Robot Framework installer. <a class="reference internal" href="#setting-up-environment">Setting up environment</a>
section has more information about setting environment variables.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">On Windows Vista and Windows 7 installing Robot Framework requires
administrator privileges. Select <tt class="docutils literal">Run as administrator</tt> from
the context menu when starting the installer.</p>
</div>
</div>
<div class="section" id="using-easy-install">
<h4><a class="toc-backref" href="#id310">Using Easy Install</a></h4>
<p>An obvious precondition for using <a class="reference external" href="http://peak.telecommunity.com/DevCenter/EasyInstall">Easy Install</a> is to have it
installed, and you can refer to its documentation on how to do that on
your operating system. The command to install Robot Framework with
Easy Install depends on whether you want to install the latest version or
some specific version:</p>
<pre class="literal-block">
easy_install robotframework         # latest version
easy_install robotframework==2.1.3  # specified version
</pre>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p class="last">If you need to use a proxy to access the Internet, you can
tell Easy Install to use it by setting the <span class="var">http_proxy</span>
environment variable.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Easy Install has a &quot;feature&quot; that unless a specific version
is given, it installs the latest possible version even if
that is an alpha or beta release. For example, if there is
2.6 beta 1 available, running <span class="cli">easy_install robotframework</span>
will install it and not the latest stable version. A
workaround is giving the version explicitly like in
<span class="cli">easy_install robotframework==2.5.7</span>.</p>
</div>
<p>On Windows the <span class="prog">pybot</span>, <span class="prog">jybot</span> and <span class="prog">rebot</span> <a class="reference internal" href="#different-runner-scripts">runner scripts</a>
are not updated when using Easy Install. A workaround is running
<span class="prog">robot_postinstall.py</span> script manually afterwards. The installation
output tells where the post-install script is located, and you can either
double click it or run it from the command line. Path to the script depends on
your Python installation, but the command to run should be something like
<span class="cli">python C:\Python25\Scripts\robot_postinstall.py</span>.</p>
<p>Updating the runner scripts is slightly fragile process in general and it
may not work with Easy Install on all environments. If the runner scripts
do not work after installation, they need to fixed manually.</p>
</div>
<div class="section" id="using-one-click-installer">
<h4><a class="toc-backref" href="#id311">Using One Click Installer</a></h4>
<p>The One Click Installer installs Robot Framework and its preconditions <a class="reference external" href="http://www.python.org/">Python</a>
and <a class="reference external" href="http://www.jython.org/">Jython</a> (optional). It also automatically <a class="reference internal" href="#setting-up-environment">sets up environment</a> so that
Robot Framework <a class="reference internal" href="#different-runner-scripts">runner scripts</a>, as well as Python and Jython executables are
in <span class="var">PATH</span>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The One Click Installer works only on Windows XP (32 bit).</p>
</div>
<p>The One Click Installer requires that you have downloaded all the required
component installers and have them in the same directory with it. More detailed
instructions and details about the supported installers are available at <a class="reference external" href="../../tools/oneclickinstaller/doc/oneclickinstaller.html">One
Click Installer's documentation</a>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">You should use this installer <em>ONLY</em> if you do not previously
have Python or Jython installed. In that case, and also if you
want to have a custom installation, you need to install
the needed components separately.</p>
</div>
</div>
<div class="section" id="manual-installation">
<h4><a class="toc-backref" href="#id312">Manual installation</a></h4>
<p>If you do not want to install Python, or for some other reason do not
want to use any automatic way of installing Robot Framework, you can
always do it manually following these steps:</p>
<ol class="arabic simple">
<li>Get the source code. All the code is in a directory (a module in
Python) called <span class="path">robot</span>. If you have a source distribution or
a version control checkout, you can find it from the <span class="path">src</span>
directory, but you can also get it from an earlier installation.</li>
<li>Copy the source code where you want to.</li>
<li>Create the needed runner scripts. If you have a source package or
a checkout, you can get templates from <span class="path">src/bin</span> directory.</li>
</ol>
</div>
<div class="section" id="standalone-jar-distribution">
<h4><a class="toc-backref" href="#id313">Standalone jar distribution</a></h4>
<p>Starting from Robot Framework 2.5.2, it is also distributed as a standalone
<tt class="docutils literal"><span class="pre">robotframework-&lt;version&gt;.jar</span></tt>, which contains both Jython and Robot
Framework. It is an easy way to get everything if you do not need to run tests
with Python. After you have downloaded the jar file, you can execute it like:</p>
<pre class="literal-block">
java -jar robotframework-2.5.2.jar --help
java -jar robotframework-2.5.2.jar mytests.txt
java -jar robotframework-2.5.2.jar --variable name:value mytests.txt
</pre>
<p>If you need to <a class="reference internal" href="#post-processing-outputs">post-process outputs</a>, <span class="cli">rebot</span> must be given as the
first argument to the jar file:</p>
<pre class="literal-block">
java -jar robotframework-2.5.2.jar rebot --help
java -jar robotframework-2.5.2.jar rebot output.xml
java -jar robotframework-2.5.2.jar rebot --name Combined outputs/*.xml
</pre>
</div>
<div class="section" id="where-files-are-installed">
<h4><a class="toc-backref" href="#id314">Where files are installed</a></h4>
<p>When an automatic installer is used, the Robot Framework code is copied
into a directory containing external Python modules. The actual
location is platform-specific, but on computers with a UNIX-like
operating system, it is normally something like
<span class="path">/usr/lib/[PythonVer]/site-packages</span>, and on Windows it is
<span class="path">[PythonInstallationDir]\Lib\site-packages</span>. The actual Robot
Framework code is in a directory named <span class="path">robot</span>, or when <a class="reference internal" href="#using-easy-install">using Easy Install</a>
in directory <span class="path">robotframework[RobotVer].py[PythonVer].egg/robot</span>.</p>
<p>Robot Framework runner scripts (<span class="prog">pybot</span>, <span class="prog">jybot</span> and
<span class="prog">rebot</span>) are created and copied into another platform-specific
location. On UNIX-like systems, they normally go to <span class="path">/usr/bin</span>
and are thus immediately available from the command line. On Windows,
the operating system does not provide a similar natural place, and
Python copies these scripts into <span class="path">[PythonInstallationDir]\Scripts</span>.</p>
</div>
<div class="section" id="setting-up-environment">
<h4><a class="toc-backref" href="#id315">Setting up environment</a></h4>
<p>After the installation, you probably want to make Robot Framework's
<a class="reference internal" href="#different-runner-scripts">runner scripts</a> easily available from the command line. On UNIX-like
systems, that should be the case automatically, but for example on
Windows, it is not. In environments where runners are not
available, the directory containing them must be set to the <span class="var">PATH</span>
environment variable.</p>
<p>Setting the <span class="var">PATH</span> environment variable on Windows:</p>
<ol class="arabic simple">
<li>Open <tt class="docutils literal">Start &gt; Settings &gt; Control Panel &gt; System &gt; Advanced &gt;
Environment Variables</tt>.  There are <tt class="docutils literal">User variables</tt> and <tt class="docutils literal">System
variables</tt>, and the difference between them is that User variables
affect only the current users, whereas System variables affect all
users.</li>
<li>To edit the existing <span class="var">PATH</span>, select <tt class="docutils literal">Edit</tt> and add
<span class="path">;[PythonInstallationDir]\Scripts\</span> at the end of the
value. Note that the leading colon (<span class="path">;</span>) is important, as it
separates different entries. To add a new value, select <tt class="docutils literal">New</tt> and
provide both the name and the value, this time without the colon.</li>
<li>Start a new command prompt for the changes to take effect.</li>
</ol>
<p>Python installer on Windows does not create
<span class="path">[PythonInstallationDir]\Scripts</span> directory, but it is automatically
created during Robot Framework installation.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Environment variable <span class="var">PYTHONCASEOK</span> should not be set on
Windows machines. Robot Framework will not work correctly with
this environment variable.</p>
</div>
</div>
<div class="section" id="verifying-installation">
<h4><a class="toc-backref" href="#id316">Verifying installation</a></h4>
<p>To verify that the installation and environment setup were successful,
type:</p>
<pre class="literal-block">
$ pybot --version
Robot Framework 2.5 (Python 2.6.5 on darwin)
</pre>
<p>To verify that Robot Framework works also with Jython, type:</p>
<pre class="literal-block">
$ jybot --version
Robot Framework 2.5 (Jython 2.5.1 on java1.6.0_07)
</pre>
<p>In both cases, the exact version and platform information can, of course,
differ from these. On Jython, you may also get some notifications from
Jython package manager upon the first execution.</p>
</div>
</div>
<div class="section" id="uninstallation">
<h3><a class="toc-backref" href="#id317">1.3.4&nbsp;&nbsp;&nbsp;Uninstallation</a></h3>
<p>If Robot Framework has been installed using a source distribution, it
can be uninstalled with command:</p>
<pre class="literal-block">
python install.py uninstall
</pre>
<p>If Robot Framework is installed from a binary distribution, it can be
uninstalled via the mechanism offered by the operating system. For
example, in Windows you simply go to <tt class="docutils literal">Control Panel &gt;
Add/Remove Programs</tt>, where Robot Framework is listed under Python.</p>
<p>If uninstallation fails somehow or you have <a class="reference internal" href="#using-easy-install">used Easy Install</a>,
Robot Framework can be uninstalled by removing the <a class="reference internal" href="#where-files-are-installed">framework code and
runner scripts</a> manually.</p>
</div>
<div class="section" id="upgrading">
<h3><a class="toc-backref" href="#id318">1.3.5&nbsp;&nbsp;&nbsp;Upgrading</a></h3>
<p>The procedure when upgrading or downgrading Robot Framework depends on
the versions used:</p>
<ul class="simple">
<li>If you are upgrading from one minor Robot Framework version to
another (for example, from 2.5 to 2.5.1), it is safe to install the
new version over the old one, unless stated otherwise.</li>
<li>If you are upgrading from one major Robot Framework version to
another (for example, from 2.1.3 to 2.5), then it is highly
recommended to uninstall the old version before the new
installation.</li>
<li>If you are downgrading, the rules are the same as for upgrading.</li>
</ul>
<p>With source distributions, you first need to get the new package, and
after that run the following command, which automatically takes care
of the uninstallation:</p>
<pre class="literal-block">
python install.py reinstall
</pre>
<p>If you are <a class="reference internal" href="#using-easy-install">using Easy Install</a>, it is enough to run:</p>
<pre class="literal-block">
easy_install robotframework==&lt;new-version&gt;
</pre>
<p>Regardless on the version or installation method, you do not need to
reinstall preconditions or set the <span class="var">PATH</span> environment variable again.</p>
</div>
</div>
<div class="section" id="demonstrations">
<h2><a class="toc-backref" href="#id296">1.4&nbsp;&nbsp;&nbsp;Demonstrations</a></h2>
<p>Robot Framework Quick Start Guide acts also as a standalone demo. It
is part of the source distribution (under <span class="path">doc/quickstart/</span>
directory), and also available as a separate download from <a class="reference external" href="http://code.google.com/p/robotframework/wiki/QuickStartGuide">project
web pages</a>.</p>
<p>Additionally, both external <a class="reference external" href="http://code.google.com/p/robotframework-seleniumlibrary">SeleniumLibrary</a> and <a class="reference external" href="http://code.google.com/p/robotframework-swinglibrary">SwingLibrary</a> have
easily executable demos available. The former contains a simple
standalone HTTP server and an application that is used as a system
under test, and the latter has a small Swing application. The actual test
case files and scripts for running demos on different systems are also
provided.</p>
</div>
</div>
<div class="section" id="creating-test-data">
<h1><a class="toc-backref" href="#id261">2&nbsp;&nbsp;&nbsp;Creating test data</a></h1>
<div class="contents local topic" id="id33">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#test-data-syntax" id="id319">2.1&nbsp;&nbsp;&nbsp;Test data syntax</a></li>
<li><a class="reference internal" href="#creating-test-cases" id="id320">2.2&nbsp;&nbsp;&nbsp;Creating test cases</a></li>
<li><a class="reference internal" href="#creating-test-suites" id="id321">2.3&nbsp;&nbsp;&nbsp;Creating test suites</a></li>
<li><a class="reference internal" href="#using-test-libraries" id="id322">2.4&nbsp;&nbsp;&nbsp;Using test libraries</a></li>
<li><a class="reference internal" href="#variables" id="id323">2.5&nbsp;&nbsp;&nbsp;Variables</a></li>
<li><a class="reference internal" href="#creating-user-keywords" id="id324">2.6&nbsp;&nbsp;&nbsp;Creating user keywords</a></li>
<li><a class="reference internal" href="#resource-and-variable-files" id="id325">2.7&nbsp;&nbsp;&nbsp;Resource and variable files</a></li>
<li><a class="reference internal" href="#advanced-features" id="id326">2.8&nbsp;&nbsp;&nbsp;Advanced features</a></li>
</ul>
</div>
<div class="section" id="test-data-syntax">
<h2><a class="toc-backref" href="#id319">2.1&nbsp;&nbsp;&nbsp;Test data syntax</a></h2>
<p>This section covers Robot Framework's overall test data
syntax. The following sections will explain how to actually create test
cases, test suites and so on.</p>
<div class="contents local topic" id="id34">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#files-and-directories" id="id327">2.1.1&nbsp;&nbsp;&nbsp;Files and directories</a></li>
<li><a class="reference internal" href="#supported-file-formats" id="id328">2.1.2&nbsp;&nbsp;&nbsp;Supported file formats</a><ul>
<li><a class="reference internal" href="#html-format" id="id329">HTML format</a></li>
<li><a class="reference internal" href="#tsv-format" id="id330">TSV format</a></li>
<li><a class="reference internal" href="#plain-text-format" id="id331">Plain text format</a></li>
<li><a class="reference internal" href="#restructuredtext-format" id="id332">reStructuredText format</a></li>
</ul>
</li>
<li><a class="reference internal" href="#test-data-tables" id="id333">2.1.3&nbsp;&nbsp;&nbsp;Test data tables</a></li>
<li><a class="reference internal" href="#rules-for-parsing-the-data" id="id334">2.1.4&nbsp;&nbsp;&nbsp;Rules for parsing the data</a><ul>
<li><a class="reference internal" href="#ignored-data" id="id335">Ignored data</a></li>
<li><a class="reference internal" href="#escaping" id="id336">Escaping</a></li>
<li><a class="reference internal" href="#handling-whitespace" id="id337">Handling whitespace</a></li>
<li><a class="reference internal" href="#dividing-test-data-to-several-rows" id="id338">Dividing test data to several rows</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="files-and-directories">
<h3><a class="toc-backref" href="#id327">2.1.1&nbsp;&nbsp;&nbsp;Files and directories</a></h3>
<p>The hierarchical structure for arranging test cases is built as follows:</p>
<ul class="simple">
<li>Test cases are created in <a class="reference internal" href="#test-case-files">test case files</a>.</li>
<li>A test case file automatically creates a <a class="reference internal" href="#creating-test-suites">test suite</a> containing
the test cases in that file.</li>
<li>A directory containing test case files forms a higher-level test
suite. Such a <a class="reference internal" href="#test-suite-directories">test suite directory</a> has suites created from test
case files as its sub test suites.</li>
<li>A test suite directory can also contain other test suite directories,
and this hierarchical structure can be as deeply nested as needed.</li>
<li>Test suite directories can have a special <a class="reference internal" href="#initialization-files">initialization file</a>.</li>
</ul>
<p>In addition to this, there are:</p>
<ul class="simple">
<li><a class="reference internal" href="#using-test-libraries">Test libraries</a> containing the lowest-level keywords.</li>
<li><a class="reference internal" href="#resource-files">Resource files</a> with <a class="reference internal" href="#variables">variables</a> and higher-level <a class="reference internal" href="#creating-user-keywords">user keywords</a>.</li>
<li><a class="reference internal" href="#variable-files">Variable files</a> to provide more flexible ways to create variables
than resource files.</li>
</ul>
</div>
<div class="section" id="supported-file-formats">
<h3><a class="toc-backref" href="#id328">2.1.2&nbsp;&nbsp;&nbsp;Supported file formats</a></h3>
<p>Robot Framework test data is defined in tabular format, using either
the hypertext markup language (HTML), tab-separated values (TSV),
plain text, or reStructuredText (reST) formats. Robot Framework
selects a parser for the test data based on the file extension. The
extension is case-insensitive, and the recognized extensions are
<span class="path">.html</span>, <span class="path">.htm</span> and <span class="path">.xhtml</span> for HTML, <span class="path">.tsv</span>
for TSV, <span class="path">.txt</span> for plain text, and <span class="path">.rst</span> or
<span class="path">.rest</span> for reStructuredText.</p>
<p>Different <a class="reference internal" href="#test-data-templates">test data templates</a> are available for HTML and TSV
formats to make it easier to get started writing tests.</p>
<div class="section" id="html-format">
<h4><a class="toc-backref" href="#id329">HTML format</a></h4>
<p>In HTML files, the test data is defined in separate tables (see the
example below). Robot Framework recognizes these <a class="reference internal" href="#test-data-tables">test data tables</a>
based on the text in their first cell. Everything outside recognized
tables is ignored.</p>
<table border="1" class="example docutils">
<caption>Using the HTML format</caption>
<colgroup>
<col width="29%" />
<col width="38%" />
<col width="17%" />
<col width="17%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>OperatingSystem</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="29%" />
<col width="38%" />
<col width="17%" />
<col width="17%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${MESSAGE}</td>
<td>Hello, world!</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="21%" />
<col width="34%" />
<col width="21%" />
<col width="23%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>My Test</td>
<td>[Documentation]</td>
<td>Example test</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>${MESSAGE}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>My Keyword</td>
<td>/tmp</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Another Test</td>
<td>Should Be Equal</td>
<td>${MESSAGE}</td>
<td>Hello, world!</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="21%" />
<col width="39%" />
<col width="21%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>My Keyword</td>
<td>[Arguments]</td>
<td>${path}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Directory Should Exist</td>
<td>${path}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<div class="section" id="editing-test-data">
<h5>Editing test data</h5>
<p>Test data in HTML files can be edited with whichever editor you
prefer, but a graphic editor, where you can actually see the tables,
is recommended.  There is also a tool called <a class="reference internal" href="#test-data-editing-tool-ride">RIDE</a>
available that is designed for editing the test data.</p>
</div>
<div class="section" id="encoding-and-entity-references">
<h5>Encoding and entity references</h5>
<p>HTML entity references (for example, <span class="code">&amp;auml;</span>) are
supported. Additionally, any encoding can be used, assuming that it is
specified in the data file. Normal HTML files must use the META
element as in the example below:</p>
<pre class="literal-block">
&lt;meta http-equiv=&quot;Content-Type&quot; content=&quot;text/html; charset=UTF-8&quot;&gt;
</pre>
<p>XHTML files should use the XML preamble as in this example:</p>
<pre class="literal-block">
&lt;?xml version=&quot;1.0&quot; encoding=&quot;Big5&quot;?&gt;
</pre>
<p>If no encoding is specified, Robot Framework uses ISO-8859-1 by default.</p>
</div>
</div>
<div class="section" id="tsv-format">
<h4><a class="toc-backref" href="#id330">TSV format</a></h4>
<p>The TSV format can be used in Robot Framework's test data for all the
same purposes as HTML. In a TSV file, all the data is in one large
table. <a class="reference internal" href="#test-data-tables">Test data tables</a> are recognized from one or more asterisks
(<span class="code">*</span>), followed by a normal table name and an optional closing
asterisks.  Everything before the first recognized table is ignored
similarly as data outside tables in HTML data.</p>
<table border="1" class="tsv-example docutils">
<caption>Using the TSV format</caption>
<colgroup>
<col width="20%" />
<col width="38%" />
<col width="21%" />
<col width="21%" />
</colgroup>
<tbody valign="top">
<tr><td>*Setting*</td>
<td>*Value*</td>
<td>*Value*</td>
<td>*Value*</td>
</tr>
<tr><td>Library</td>
<td>OperatingSystem</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>*Variable*</td>
<td>*Value*</td>
<td>*Value*</td>
<td>*Value*</td>
</tr>
<tr><td>${MESSAGE}</td>
<td>Hello, world!</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>*Test Case*</td>
<td>*Action*</td>
<td>*Argument*</td>
<td>*Argument*</td>
</tr>
<tr><td>My Test</td>
<td>[Documentation]</td>
<td>Example test</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>${MESSAGE}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>My Keyword</td>
<td>/tmp</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Another Test</td>
<td>Should Be Equal</td>
<td>${MESSAGE}</td>
<td>Hello, world!</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>*Keyword*</td>
<td>*Action*</td>
<td>*Argument*</td>
<td>*Argument*</td>
</tr>
<tr><td>My Keyword</td>
<td>[Arguments]</td>
<td>${path}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Directory Should Exist</td>
<td>${path}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<div class="section" id="id35">
<h5>Editing test data</h5>
<p>You can create and edit TSV files in any spreadsheet program, such as
Microsoft Excel. Select the tab-separated format when you save the
file and remember to set the file extension to <span class="path">.tsv</span>. It is
also a good idea to turn all automatic corrections off and configure
the tool to treat all values in the file as plain text.</p>
<p>TSV files are relatively easy to edit with any text editor,
especially if the editor supports visually separating tabs from
spaces. The TSV format is also supported by <a class="reference internal" href="#test-data-editing-tool-ride">RIDE</a>.</p>
<p>Robot Framework parses TSV data by first splitting all the content
into rows and then rows into cells on the basis of the tabular
characters. Spreadsheet programs sometimes surround cells with quotes
(for example, <span class="code">&quot;my value&quot;</span>) and Robot Framework removes
them. Possible quotes inside the data are doubled (for example,
<span class="code">&quot;my &quot;&quot;quoted&quot;&quot; value&quot;</span>) and also this is handled correctly.  If
you are using a spreadsheet program to create TSV data, you should not
need to pay attention to this, but if you create data
programmatically, you have to follow the same quoting conventions as
spreadsheets.</p>
</div>
<div class="section" id="encoding">
<h5>Encoding</h5>
<p>TSV files are always expected to use UTF-8 encoding. Because ASCII is
a subset of UTF-8, plain ASCII is naturally supported too.</p>
</div>
</div>
<div class="section" id="plain-text-format">
<h4><a class="toc-backref" href="#id331">Plain text format</a></h4>
<p>The plain text format is technically otherwise similar to the <a class="reference internal" href="#tsv-format">TSV
format</a> but the separator between the cells is different. The TSV
format uses tabs, but in the plain text format you can use either two
or more spaces or a pipe character surrounded with spaces <span class="code">( | )</span>.</p>
<p>The <a class="reference internal" href="#test-data-tables">test data tables</a> must have one or more asterisk before their
names similarly as in the TSV format. Otherwise asterisks and possible
spaces in the table header are ignored so, for example, <span class="code">***
Settings ***</span> and <span class="code">*Settings</span> work the same way. Also similarly
as in the TSV format, everything before the first table is ignored.</p>
<p>In plain text files tabs are automatically converted to two
spaces. This allows using a single tab as a separator similarly as in
the TSV format. Notice, however, that in the plain text format
multiple tabs are considered to be a single separator whereas in the
TSV format every tab would be a separator.</p>
<div class="section" id="space-separated-format">
<h5>Space separated format</h5>
<p>The number of spaces used as separator can vary, as long as there are
at least two spaces, and it is thus possible to align the data nicely.
This is a clear benefit over editing the TSV format in a text editor
because with TSV the alignment cannot be controlled.</p>
<pre class="literal-block">
*** Settings ***
Library     OperatingSystem

*** Variables ***
${MESSAGE}  Hello, world!

*** Test Cases ***
My Test  [Documentation]  Example test
    Log         ${MESSAGE}
    My Keyword  /tmp

Another Test
    Should Be Equal  ${MESSAGE}  Hello, world!

*** Keywords ***
My Keyword  [Arguments]  ${path}
    Directory Should Exist  ${path}
</pre>
<p>Because space is used as separator, all empty cells must be <a class="reference internal" href="#escaping">escaped</a>
with <span class="var">${EMPTY}</span> variable or a single backslash. Otherwise
<a class="reference internal" href="#handling-whitespace">handling whitespace</a> is not different than in other test data
because leading, trailing, and consecutive spaces must always be
escaped.</p>
</div>
<div class="section" id="pipe-and-space-separated-format">
<h5>Pipe and space separated format</h5>
<p>The biggest problem of the space delimited format is that visually
separating keywords form arguments can be tricky. This is a problem
especially if keywords take a lot of arguments and/or arguments
contain spaces. In such cases the pipe and space delimited variant can
work better because it makes the cell boundary more visible.</p>
<pre class="literal-block">
| *Setting*  |     *Value*     |
| Library    | OperatingSystem |

| *Variable* |     *Value*     |
| ${MESSAGE} | Hello, world!   |

| *Test Case*  | *Action*        | *Argument*   |
| My Test      | [Documentation] | Example test |
|              | Log             | ${MESSAGE}   |
|              | My Keyword      | /tmp         |
| Another Test | Should Be Equal | ${MESSAGE}   | Hello, world!

| *Keyword*  |
| My Keyword | [Arguments] | ${path}
|            | Directory Should Exist | ${path}
</pre>
<p>A plain text file can contain test data in both space-only and
space-and-pipe separated formats, but a single line must always use
the same separator. Pipe and space separated lines are recognized by
the mandatory leading pipe, but the pipe at the end of the line is
optional. There must always be at least one space on both sides of the
pipe (except at the beginning and end) but there is no need to align
the pipes other than if it makes the data more clear.</p>
<p>There is no need to escape empty cells (other than the <a class="reference internal" href="#escaping">trailing empty
cells</a>) when using the pipe and space separated format. The only
thing to take into account is that possible pipes surrounded by spaces
in the actual test data must be escaped with a backslash:</p>
<pre class="literal-block">
| ${file count} = | Execute Command | ls -1 *.txt \| wc -l |
| Should Be Equal | ${file count}   | 42                   |
</pre>
</div>
<div class="section" id="editing-and-encoding">
<h5>Editing and encoding</h5>
<p>One of the biggest benefit of the plain text format over HTML and TSV
is that editing it using normal text editors is very easy. For <a class="reference external" href="http://www.gnu.org/software/emacs/">Emacs</a>
there is even a special <a class="reference external" href="http://code.google.com/p/robot-mode/">robot-mode.el</a> that provides syntax
highlighting and keyword completion. The plain text format is also
supported by <a class="reference internal" href="#test-data-editing-tool-ride">RIDE</a>, although it only supports the space separated
variant.</p>
<p>Similarly as with the TSV test data, plain text files are always expected
to use UTF-8 encoding. As a consequence also ASCII files are supported.</p>
</div>
</div>
<div class="section" id="restructuredtext-format">
<h4><a class="toc-backref" href="#id332">reStructuredText format</a></h4>
<p>reStructuredText (reST) is a easy-to-read plain text markup syntax that
is commonly used for documentation of Python projects (including
Python itself, as well as this user guide). Using reST with Robot
Framework allows you to mix richly formatted documents and tables that
specify test data in a concise text format that is easy to work with
using simple text editors, diff tools, and source control systems.</p>
<p>Tools to process reStructuredText are freely available as part of the
<a class="reference external" href="http://docutils.sourceforge.net/rst.html">docutils</a> project, and there is a <a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">quick reference guide</a> that
shows the most common formatting constructs including the tables used
by Robot Framework. Notice that Robot Framework converts test data in
reST format internally to HTML before starting to actually parse
it. The data must thus follow reST syntax strictly or otherwise
processing it will not succeed.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Using reST files with Robot Framework requires the Python docutils
module to be installed.</p>
</div>
<p>In reST files, test data is defined in tables within the document, similar to
the HTML format. Robot Framework identifies <a class="reference internal" href="#test-data-tables">test data tables</a> based on the
text in the first cell and all content outside of the recognized table types is
ignored.</p>
<p>An example of each of the four test data tables is shown below
using the reST <cite>Simple Tables</cite> syntax. Note that <span class="code">\</span> or
<span class="code">..</span> must be used to indicate an empty cell in the first column
of the table:</p>
<pre class="literal-block">
============  ================  =======  =======
  Setting          Value         Value    Value
============  ================  =======  =======
Library       OperatingSystem
============  ================  =======  =======


============  ================  =======  =======
  Variable         Value         Value    Value
============  ================  =======  =======
${MESSAGE}    Hello, world!
============  ================  =======  =======


============  ===================  ============  =============
 Test Case          Action           Argument      Argument
============  ===================  ============  =============
My Test       [Documentation]      Example test
\             Log                  ${MESSAGE}
\             My Keyword           /tmp
\
Another Test  Should Be Equal      ${MESSAGE}    Hello, world!
============  ===================  ============  =============


============  ======================  ============  ==========
 Keyword            Action             Argument     Argument
============  ======================  ============  ==========
My Keyword    [Arguments]             ${path}
\             Directory Should Exist  ${path}
============  ======================  ============  ==========
</pre>
<div class="section" id="id42">
<h5>Editing test data</h5>
<p>Test data in reST files can be edited with any text editor. It is recommended
that the editor be configured to use a monospace font to aid with alignment
of table elements.</p>
<p>Note that <a class="reference internal" href="#test-data-editing-tool-ride">RIDE</a> does not support direct editing of test data in reST source
files.</p>
</div>
<div class="section" id="temporary-files-when-using-rest">
<h5>Temporary files when using reST</h5>
<p>Unlike HTML or TSV formats, Robot Framework does not parse reST files
directly.  Instead, docutils is used to automatically transform reST
source files into temporary HTML files that are subsequently read by
Robot. These temporary files are removed immediately after being
read. This HTML file generation and cleanup is handled internally by
Robot Framework, it does not require the user to directly invoke
docutils tools.</p>
</div>
<div class="section" id="syntax-errors-in-rest-source-files">
<h5>Syntax errors in reST source files</h5>
<p>If reST file is not syntactically correct (a malformed table for
example), the reST-to-HTML conversion will not take place and no test
cases will be read from that file. When this occurs, Robot Framework
will show the docutils error message in its console output showing the
filename, line number, source context, and type of error.</p>
</div>
</div>
</div>
<div class="section" id="test-data-tables">
<h3><a class="toc-backref" href="#id333">2.1.3&nbsp;&nbsp;&nbsp;Test data tables</a></h3>
<p>Test data is structured in four types of tables listed below. These
test data tables are identified by the first cell of the table, and
the last column in the table below lists different aliases that can be
used as a table name.</p>
<table border="1" class="tabular docutils">
<caption>Different test data tables</caption>
<colgroup>
<col width="18%" />
<col width="57%" />
<col width="25%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Table name</th>
<th class="head">Used for</th>
<th class="head">Aliases</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Setting
table</td>
<td><div class="first last line-block">
<div class="line">1) Importing <a class="reference internal" href="#using-test-libraries">test libraries</a>,
<a class="reference internal" href="#resource-files">resource files</a> and <a class="reference internal" href="#variable-files">variable files</a></div>
<div class="line">2) Defining metadata for <a class="reference internal" href="#creating-test-suites">test suites</a>
and <a class="reference internal" href="#creating-test-cases">test cases</a></div>
</div>
</td>
<td>Setting, Settings,
Metadata</td>
</tr>
<tr><td>Variable
table</td>
<td>Defining <a class="reference internal" href="#variables">variables</a> that can be used
elsewhere in the test data</td>
<td>Variable,
Variables</td>
</tr>
<tr><td>Test case
table</td>
<td><a class="reference internal" href="#creating-test-cases">Creating test cases</a> from available
keywords</td>
<td>Test Case,
Test Cases</td>
</tr>
<tr><td>Keyword
table</td>
<td><a class="reference internal" href="#creating-user-keywords">Creating user keywords</a> from existing
lower-level keywords</td>
<td>Keyword, Keywords,
User Keyword,
User Keywords</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="rules-for-parsing-the-data">
<h3><a class="toc-backref" href="#id334">2.1.4&nbsp;&nbsp;&nbsp;Rules for parsing the data</a></h3>
<div class="section" id="ignored-data">
<h4><a class="toc-backref" href="#id335">Ignored data</a></h4>
<p>When Robot Framework parses the test data, it ignores:</p>
<ul class="simple">
<li>All tables that do not start with a recognized table name in the first cell.</li>
<li>Everything else on the first row of a table apart from the first cell.</li>
<li>Data outside tables in HTML/reST and data before the first table in TSV.</li>
<li>All empty rows, which means these kinds of rows can be used to make
the tables more readable.</li>
<li>All empty cells at the end of rows; you must add a backslash (\) to
prevent such cells from being ignored.</li>
<li>All single backslashes (\); they are used as an escape character.</li>
<li>All characters following a hash mark (#), if it is the first
character of a cell; this means that hash marks can be used to enter
comments in the test data.</li>
<li>All formatting in the HTML/reST test data.</li>
</ul>
<p>When Robot Framework ignores some data, this data is not available in
any resulting reports and, additionally, most tools used with Robot
Framework also ignore them. To add information that is visible in
Robot Framework outputs, or available to, for example, <a class="reference internal" href="#test-data-editing-tool-ride">RIDE</a>,
place it to the documentation or other metadata of test cases or suites,
or log with the <span class="name">Log</span> or <span class="name">Comment</span> keywords available
from the <a class="reference internal" href="#builtin-library">BuiltIn library</a>.</p>
</div>
<div class="section" id="escaping">
<h4><a class="toc-backref" href="#id336">Escaping</a></h4>
<p>The escape character for the Robot Framework parser is the backslash
(<span class="code">\</span>).  The escape character can be used as follows:</p>
<ul class="simple">
<li>To escape special characters so that their literal values are
used:<ul>
<li><span class="code">\${notvar}</span> means a literal string <span class="code">${notvar}</span> that
looks like a <a class="reference internal" href="#variables">variable</a></li>
<li><span class="code">\\</span> means a single backslash (for example, <span class="code">C:\\Temp</span>)</li>
<li><span class="code">\#</span> means a literal hash (#) mark, even at the beginning of a cell</li>
</ul>
</li>
<li>To affect <a class="reference internal" href="#handling-whitespace">the parsing of whitespaces</a>.</li>
<li>To prevent ignoring empty cells at the end of a row (this requires
<span class="code">\</span> to be in the appropriate cell). Another possibility is
using <a class="reference internal" href="#space-and-empty-variables">built-in variable</a> <span class="var">${EMPTY}</span>.</li>
<li>To escape indented cells in <a class="reference internal" href="#for-loops">for loops</a> when using the <a class="reference internal" href="#plain-text-format">plain text format</a>.</li>
</ul>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">These escaping rules are applied only to arguments to
keywords and values to settings. They are not used, for
example, with keyword and test case names.</p>
</div>
</div>
<div class="section" id="handling-whitespace">
<h4><a class="toc-backref" href="#id337">Handling whitespace</a></h4>
<p>Robot Framework handles whitespace, such as spaces, newlines and tabs,
the same way as they are handled in HTML. This means that Robot Framework:</p>
<ul class="simple">
<li>Removes leading and trailing whitespace in all cells.</li>
<li>Changes multiple consecutive spaces into single spaces.</li>
<li>Converts all newlines and tabs into spaces.</li>
</ul>
<p>To prevent Robot Framework from parsing data according to these rules, a backslash can be used:</p>
<ul class="simple">
<li>Before leading spaces, for example <span class="code">\ some text</span>.</li>
<li>Between consecutive spaces, for example <span class="code">text \ \ more text</span>.</li>
<li>After trailing spaces, for example <span class="code">some text \ \</span>.</li>
<li>As <span class="code">\n</span> to create a newline, for example <span class="code">first line\n2nd line</span>.</li>
<li>As <span class="code">\t</span> to create a tab character, for example <span class="code">text\tmore text</span>.</li>
<li>As <span class="code">\r</span> to create a carriage return, for example <span class="code">text\rmore text</span>.</li>
</ul>
<p>Another, and often clearer, possibility for representing leading,
trailing, or consecutive spaces is using <a class="reference internal" href="#space-and-empty-variables">built-in variable</a>
<span class="var">${SPACE}</span>. The <a class="reference internal" href="#extended-variable-syntax">extended variable syntax</a> even allows syntax
like <span class="var">${SPACE * 8}</span> which makes handling consecutive spaces very simple.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Possible un-escaped whitespace character after the <span class="code">\n</span> is
ignored to allow wrapping long lines containing newlines. This
means that <span class="code">two lines\nhere</span> and <span class="code">two lines\n here</span>
are equivalent. An exception to this rule is that the whitespace
character is not ignored inside the <a class="reference internal" href="#extended-variable-syntax">extended variable syntax</a>.</p>
</div>
</div>
<div class="section" id="dividing-test-data-to-several-rows">
<h4><a class="toc-backref" href="#id338">Dividing test data to several rows</a></h4>
<p>If there is more data than readily fits a row, it possible to use ellipsis
(<span class="code">...</span>) to continue the previous line. In test case and user keyword tables,
the ellipsis must be preceded by at least one empty cell.  In settings and
variable tables, it can be placed directly under the setting or variable name.</p>
<p>In all tables, all empty cells before the ellipsis are ignored.</p>
<p>Additionally, values of settings that take only one value (mainly
documentations) can be split to several columns. These values
will be then catenated together with spaces when the test data is
parsed.</p>
<p>All these syntaxes are illustrated in the following examples. In the
first three tables test data has not been split, and
the following three illustrate how fewer columns are needed after
splitting the data to several rows.</p>
<table border="1" class="example docutils">
<caption>Test data that has not been split</caption>
<colgroup>
<col width="22%" />
<col width="13%" />
<col width="13%" />
<col width="13%" />
<col width="13%" />
<col width="13%" />
<col width="13%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Default Tags</td>
<td>tag-1</td>
<td>tag-2</td>
<td>tag-3</td>
<td>tag-4</td>
<td>tag-5</td>
<td>tag-6</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="19%" />
<col width="13%" />
<col width="13%" />
<col width="13%" />
<col width="13%" />
<col width="13%" />
<col width="13%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>&#64;{LIST}</td>
<td>this</td>
<td>list</td>
<td>has</td>
<td>quite</td>
<td>many</td>
<td>items</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="14%" />
<col width="22%" />
<col width="19%" />
<col width="8%" />
<col width="9%" />
<col width="8%" />
<col width="8%" />
<col width="6%" />
<col width="6%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Arg</th>
<th class="head">Arg</th>
<th class="head">Arg</th>
<th class="head">Arg</th>
<th class="head">Arg</th>
<th class="head">Arg</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>[Documentation]</td>
<td>Documentation
for this test
case. This
can get quite
long...</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>[Tags]</td>
<td>t-1</td>
<td>t-2</td>
<td>t-3</td>
<td>t-4</td>
<td>t-5</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>Do X</td>
<td>one</td>
<td>two</td>
<td>three</td>
<td>four</td>
<td>five</td>
<td>six</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>${var} =</td>
<td>Get X</td>
<td>1</td>
<td>2</td>
<td>3</td>
<td>4</td>
<td>5</td>
<td>6</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<caption>Test data split to several rows</caption>
<colgroup>
<col width="36%" />
<col width="21%" />
<col width="21%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Default Tags</td>
<td>tag-1</td>
<td>tag-2</td>
<td>tag-3</td>
</tr>
<tr><td>...</td>
<td>tag-4</td>
<td>tag-5</td>
<td>tag-6</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="32%" />
<col width="23%" />
<col width="23%" />
<col width="23%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>&#64;{LIST}</td>
<td>this</td>
<td>list</td>
<td>has</td>
</tr>
<tr><td>...</td>
<td>quite</td>
<td>many</td>
<td>items</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="18%" />
<col width="26%" />
<col width="23%" />
<col width="16%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>[Documentation]</td>
<td>Documentation</td>
<td>for this</td>
<td>test case.</td>
</tr>
<tr><td></td>
<td>...</td>
<td>This can get</td>
<td>quite</td>
<td>long...</td>
</tr>
<tr><td></td>
<td>[Tags]</td>
<td>t-1</td>
<td>t-2</td>
<td>t-3</td>
</tr>
<tr><td></td>
<td>...</td>
<td>t-4</td>
<td>t-5</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Do X</td>
<td>one</td>
<td>two</td>
<td>three</td>
</tr>
<tr><td></td>
<td>...</td>
<td>four</td>
<td>five</td>
<td>six</td>
</tr>
<tr><td></td>
<td>${var} =</td>
<td>Get X</td>
<td>1</td>
<td>2</td>
</tr>
<tr><td></td>
<td>...</td>
<td>3</td>
<td>4</td>
<td>5</td>
</tr>
<tr><td></td>
<td>...</td>
<td>...</td>
<td>6</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Empty cells before ellipsis are allowed generally only in Robot
Framework 2.5.2 and newer. In earlier versions a single leading
empty cell is allowed inside <a class="reference internal" href="#for-loops">for loops</a> but not otherwise.</p>
</div>
<div class="section" id="splitting-test-data-in-rest-tables">
<h5>Splitting test data in reST tables</h5>
<p>In the plain text markup for reST tables, there are two types of table
syntax that can be used to create test data. When using the <cite>Simple
Tables</cite> syntax, a <span class="code">\</span> or <span class="code">..</span> is required in the first cell
of a continued row in addition to the <span class="code">...</span> required by Robot Framework.</p>
<p>Here is an example using reST <cite>Simple Table</cite> format:</p>
<pre class="literal-block">
===========  ================  ==============  ==========  ==========
 Test Case       Action           Argument      Argument    Argument
===========  ================  ==============  ==========  ==========
Example      [Documentation]   Documentation   for this    test case.
\            ...               This can get    quite       long...
\            [Tags]            t-1             t-2         t-3
\            ...               t-4             t-5
\            Do X              one             two         three
\            ...               four            five        six
\            ${var} =          Get X           1           2
\            ...               3               4           5
\            ...               6
===========  ================  ==============  ==========  ==========
</pre>
<p>For <cite>Grid Table</cite> syntax, the first cell in a continued row may be blank,
and the second cell should contain <span class="code">...</span> as with HTML tables:</p>
<pre class="literal-block">
+-----------+-------------------+---------------+------------+------------+
| Test Case |      Action       |   Argument    |  Argument  |  Argument  |
+===========+===================+===============+============+============+
| Example   | [Documentation]   | Documentation | for this   | test case. |
+-----------+-------------------+---------------+------------+------------+
|           | ...               | This can get  | quite      | long...    |
+-----------+-------------------+---------------+------------+------------+
|           | [Tags]            | t-1           | t-2        | t-3        |
+-----------+-------------------+---------------+------------+------------+
|           | ...               | t-4           | t-5        |            |
+-----------+-------------------+---------------+------------+------------+
|           | Do X              | one           | two        | three      |
+-----------+-------------------+---------------+------------+------------+
|           | ...               | four          | five       | six        |
+-----------+-------------------+---------------+------------+------------+
|           | ${var} =          | Get X         | 1          | 2          |
+-----------+-------------------+---------------+------------+------------+
|           | ...               | 3             | 4          | 5          |
+-----------+-------------------+---------------+------------+------------+
|           | ...               | 6             |            |            |
+-----------+-------------------+---------------+------------+------------+
</pre>
</div>
</div>
</div>
</div>
<div class="section" id="creating-test-cases">
<h2><a class="toc-backref" href="#id320">2.2&nbsp;&nbsp;&nbsp;Creating test cases</a></h2>
<p>This section describes the overall test case syntax. Organizing test
cases into <a class="reference internal" href="#creating-test-suites">test suites</a> using <a class="reference internal" href="#test-case-files">test case files</a> and <a class="reference internal" href="#test-suite-directories">test suite
directories</a> is discussed in the next section.</p>
<div class="contents local topic" id="id46">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#test-case-syntax" id="id339">2.2.1&nbsp;&nbsp;&nbsp;Test case syntax</a><ul>
<li><a class="reference internal" href="#basic-syntax" id="id340">Basic syntax</a></li>
<li><a class="reference internal" href="#settings-in-the-test-case-table" id="id341">Settings in the Test Case table</a></li>
<li><a class="reference internal" href="#test-case-related-settings-in-the-setting-table" id="id342">Test case related settings in the Setting table</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-arguments" id="id343">2.2.2&nbsp;&nbsp;&nbsp;Using arguments</a><ul>
<li><a class="reference internal" href="#required-arguments" id="id344">Required arguments</a></li>
<li><a class="reference internal" href="#default-values" id="id345">Default values</a></li>
<li><a class="reference internal" href="#variable-number-of-arguments" id="id346">Variable number of arguments</a></li>
<li><a class="reference internal" href="#named-arguments" id="id347">Named arguments</a></li>
<li><a class="reference internal" href="#arguments-embedded-to-keyword-names" id="id348">Arguments embedded to keyword names</a></li>
</ul>
</li>
<li><a class="reference internal" href="#test-case-name-and-documentation" id="id349">2.2.3&nbsp;&nbsp;&nbsp;Test case name and documentation</a></li>
<li><a class="reference internal" href="#tagging-test-cases" id="id350">2.2.4&nbsp;&nbsp;&nbsp;Tagging test cases</a></li>
<li><a class="reference internal" href="#test-setup-and-teardown" id="id351">2.2.5&nbsp;&nbsp;&nbsp;Test setup and teardown</a></li>
<li><a class="reference internal" href="#test-templates" id="id352">2.2.6&nbsp;&nbsp;&nbsp;Test templates</a></li>
<li><a class="reference internal" href="#different-test-case-styles" id="id353">2.2.7&nbsp;&nbsp;&nbsp;Different test case styles</a><ul>
<li><a class="reference internal" href="#keyword-driven-style" id="id354">Keyword-driven style</a></li>
<li><a class="reference internal" href="#data-driven-style" id="id355">Data-driven style</a></li>
<li><a class="reference internal" href="#behavior-driven-style" id="id356">Behavior-driven style</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="test-case-syntax">
<h3><a class="toc-backref" href="#id339">2.2.1&nbsp;&nbsp;&nbsp;Test case syntax</a></h3>
<div class="section" id="basic-syntax">
<h4><a class="toc-backref" href="#id340">Basic syntax</a></h4>
<p>Test cases are constructed in test case tables from the available
keywords. Keywords can be imported from <a class="reference internal" href="#using-test-libraries">test libraries</a> or <a class="reference internal" href="#resource-files">resource
files</a>, or created in the <a class="reference internal" href="#creating-user-keywords">keyword table</a> of the test case file
itself.</p>
<p>The first column in the test case table contains test case names. A
test case starts from the row with something in this column and
continues to the next test case name or to the end of the table. It is
an error to have something between the table headers and the first
test.</p>
<p>The second column normally has keyword names. An exception to this rule
is <a class="reference internal" href="#user-keyword-return-values">setting variables from keyword return values</a>, when the second and
possibly also the subsequent columns contain variable names and a keyword
name is located after them. In either case, columns after the keyword name
contain possible arguments to the specified keyword.</p>
<table border="1" class="example docutils" id="example-tests">
<caption>Example test cases</caption>
<colgroup>
<col width="23%" />
<col width="35%" />
<col width="23%" />
<col width="19%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Valid Login</td>
<td>Open Login Page</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Input Name</td>
<td>demo</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Input Password</td>
<td>mode</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Submit Credentials</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Welcome Page Should Be Open</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Setting Variables</td>
<td>Do Something</td>
<td>first argument</td>
<td>second argument</td>
</tr>
<tr><td></td>
<td>${value} =</td>
<td>Get Some Value</td>
<td></td>
</tr>
<tr><td></td>
<td>Should Be Equal</td>
<td>${value}</td>
<td>Expected value</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="settings-in-the-test-case-table">
<h4><a class="toc-backref" href="#id341">Settings in the Test Case table</a></h4>
<p>Test cases can also have their own settings. Setting names are always
in the second column, where keywords normally are, and their values
are in the subsequent columns. Setting names have square brackets around
them to distinguish them from keywords. The available settings are listed
below and explained later in this section.</p>
<dl class="docutils">
<dt><span class="opt">[Documentation]</span></dt>
<dd>Used for specifying a <a class="reference internal" href="#test-case-name-and-documentation">test case documentation</a>.</dd>
<dt><span class="opt">[Tags]</span></dt>
<dd>Used for <a class="reference internal" href="#tagging-test-cases">tagging test cases</a>.</dd>
<dt><span class="opt">[Setup]</span>, <span class="opt">[Teardown]</span></dt>
<dd>Specify <a class="reference internal" href="#test-setup-and-teardown">test setup and teardown</a>. Have also synonyms
<span class="opt">[Precondition]</span> and <span class="opt">[Postcondition]</span>,
respectively.</dd>
<dt><span class="opt">[Template]</span></dt>
<dd>Specifies the <a class="reference internal" href="#test-templates">template keyword</a> to use. The test itself will contain only
data to use as arguments to that keyword.</dd>
<dt><span class="opt">[Timeout]</span></dt>
<dd>Used for setting a <a class="reference internal" href="#test-case-timeout">test case timeout</a>. <a class="reference internal" href="#timeouts">Timeouts</a> are discussed in
their own section.</dd>
</dl>
<table border="1" class="example docutils">
<caption>Example test case with settings</caption>
<colgroup>
<col width="23%" />
<col width="35%" />
<col width="23%" />
<col width="19%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Test With Settings</td>
<td>[Documentation]</td>
<td>Another dummy test</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Tags]</td>
<td>dummy</td>
<td>owner-johndoe</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>Hello, world!</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="test-case-related-settings-in-the-setting-table">
<h4><a class="toc-backref" href="#id342">Test case related settings in the Setting table</a></h4>
<p>The Setting table can have the following test case related
settings. These settings are mainly default values for the
test case specific settings listed earlier.</p>
<dl class="docutils">
<dt><span class="opt">Force Tags</span>, <span class="opt">Default Tags</span></dt>
<dd>The forced and default values for <a class="reference internal" href="#tagging-test-cases">tags</a>.</dd>
<dt><span class="opt">Test Setup</span>, <span class="opt">Test Teardown</span></dt>
<dd>The default values for <a class="reference internal" href="#test-setup-and-teardown">test setup and teardown</a>. Have also synonyms
<span class="opt">Test Precondition</span> and <span class="opt">Test Postcondition</span>,
respectively.</dd>
<dt><span class="opt">Test Template</span></dt>
<dd>The default <a class="reference internal" href="#test-templates">template keyword</a> to use.</dd>
<dt><span class="opt">Test Timeout</span></dt>
<dd>The default value for <a class="reference internal" href="#test-case-timeout">test case timeout</a>. <a class="reference internal" href="#timeouts">Timeouts</a> are discussed in
their own section.</dd>
</dl>
</div>
</div>
<div class="section" id="using-arguments">
<h3><a class="toc-backref" href="#id343">2.2.2&nbsp;&nbsp;&nbsp;Using arguments</a></h3>
<p>The earlier examples have already demonstrated keywords taking
different arguments, and this section discusses this important
functionality more thoroughly. How to actually implement <a class="reference internal" href="#user-keyword-arguments">user
keywords</a> and <a class="reference internal" href="#keyword-arguments">library keywords</a> with different arguments is
discussed in separate sections.</p>
<p>Keywords can accept zero or more arguments, and some arguments may
have default values. What arguments a keyword accepts depends on its
implementation, and typically the best place to search this
information is keyword's documentation. In the examples in this
section the documentation is expected to be generated using the
<a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> tool, but the same information is available on
documentation generated by generic documentation tools such as
<span class="prog">javadoc</span>.</p>
<div class="section" id="required-arguments">
<h4><a class="toc-backref" href="#id344">Required arguments</a></h4>
<p>Most keywords have a certain number of arguments that must always be
given.  In the keyword documentation this is denoted by specifying the
argument names separated with a comma like <span class="code">first, second,
third</span>. The argument names actually do not matter in this case, except
that they should explain what the argument does, but it is important
to have exactly the same number of arguments as specified in the
documentation. Using too few or too many arguments will result in an
error.</p>
<p>The test below uses keywords <span class="name">Create Directory</span> and <span class="name">Copy
File</span> from the <span class="name">OperatingSystem</span> library. Their arguments are
specified as <span class="code">path</span> and <span class="code">source, destination</span> which means
that they take one and two arguments, respectively. The last keyword,
<span class="name">No Operation</span> from <span class="name">BuiltIn</span>, takes no arguments.</p>
<table border="1" class="example docutils">
<caption>Keywords with positional arguments</caption>
<colgroup>
<col width="20%" />
<col width="25%" />
<col width="28%" />
<col width="28%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>Create Directory</td>
<td>${TEMPDIR}/stuff</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Copy File</td>
<td>${CURDIR}/file.txt</td>
<td>${TEMPDIR}/stuff</td>
</tr>
<tr><td></td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="default-values">
<h4><a class="toc-backref" href="#id345">Default values</a></h4>
<p>Arguments often have default values which can either be given or
not. In the documentation the default value is typically separated
from the argument name with an equal sign like <span class="code">name=default
value</span>, but with keywords implemented using Java there may be
<a class="reference internal" href="#default-values-with-java">multiple implementations</a> of the same keyword with different
arguments instead. It is possible that all the arguments have default
values, but there cannot be any positional arguments after arguments
with default values.</p>
<p>Using default values is illustrated by the example below that uses
<span class="name">Create File</span> keyword which has arguments <span class="code">path, content=,
encoding=UTF-8</span>. Trying to use it without any arguments or more than
three arguments would not work.</p>
<table border="1" class="example docutils">
<caption>Keywords with arguments having default values</caption>
<colgroup>
<col width="15%" />
<col width="19%" />
<col width="29%" />
<col width="23%" />
<col width="14%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>Create File</td>
<td>${TEMPDIR}/empty.txt</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Create File</td>
<td>${TEMPDIR}/utf-8.txt</td>
<td>Hyvä esimerkki</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Create File</td>
<td>${TEMPDIR}/iso-8859-1.txt</td>
<td>Hyvä esimerkki</td>
<td>ISO-8859-1</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="variable-number-of-arguments">
<h4><a class="toc-backref" href="#id346">Variable number of arguments</a></h4>
<p>It is also possible to create keywords that accept any number of
arguments. These arguments can be combined with mandatory arguments
and arguments with default values, but the so called <cite>varargs</cite> are
always the last ones. In the documentation they typically have an
asterisk before the argument name like <span class="code">*varargs</span> , but there
are again <a class="reference internal" href="#variable-number-of-arguments-with-java">differences with Java libraries</a>.</p>
<p><span class="name">Remove Files</span> and <span class="name">Join Paths</span> keywords used in the
example below have arguments <span class="code">*paths</span> and <span class="code">base, *parts</span>,
respectively. The former can be used with any number of arguments, but
the latter requires at least one argument.</p>
<table border="1" class="example docutils">
<caption>Keywords with variable number of arguments</caption>
<colgroup>
<col width="16%" />
<col width="20%" />
<col width="21%" />
<col width="21%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>Remove Files</td>
<td>${TEMPDIR}/f1.txt</td>
<td>${TEMPDIR}/f2.txt</td>
<td>${TEMPDIR}/f3.txt</td>
</tr>
<tr><td></td>
<td>&#64;{paths} =</td>
<td>Join Paths</td>
<td>${TEMPDIR}</td>
<td>f1.txt</td>
</tr>
<tr><td></td>
<td>...</td>
<td>f2.txt</td>
<td>f3.txt</td>
<td>f4.txt</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="named-arguments">
<h4><a class="toc-backref" href="#id347">Named arguments</a></h4>
<p>When a keyword accepts more than one argument with a default value,
overriding only the last one using positional argument is not
possible. For example, if a keyword having arguments <span class="code">arg1=a,
arg2=b, arg3=c</span> is used as in the test below, its arguments
<span class="code">arg1</span> and <span class="code">arg2</span> both get an empty string as value
instead of their default values.</p>
<table border="1" class="example docutils">
<caption>Overriding default values with positional arguments</caption>
<colgroup>
<col width="26%" />
<col width="21%" />
<col width="18%" />
<col width="18%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Positional Arguments</td>
<td>[Documentation]</td>
<td>1st and 2nd</td>
<td>argument get</td>
<td>empty strings</td>
</tr>
<tr><td></td>
<td>Example Keyword</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>value</td>
</tr>
</tbody>
</table>
<p>To make giving only some of the arguments that expect default values
easier, new <cite>named arguments</cite> syntax was added in Robot Framework
2.5. With this syntax the arguments that need to override their
default values are given immediately after the required arguments in
format <span class="code">argname=value</span>. The arguments that should use defaults
can be simply be left out. How this works in practice is illustrated
by the example test below that uses the same keyword as the above
example. In this example the arguments that are not specified will get
their default values.</p>
<table border="1" class="example docutils">
<caption>Keywords with named arguments</caption>
<colgroup>
<col width="26%" />
<col width="21%" />
<col width="18%" />
<col width="18%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Named Arguments</td>
<td>[Documentation]</td>
<td>Not specified</td>
<td>arguments get</td>
<td>default values</td>
</tr>
<tr><td></td>
<td>Example Keyword</td>
<td>arg3=value</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Example Keyword</td>
<td>arg2=xxx</td>
<td>arg3=yyy</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>The named argument syntax can naturally be used with arguments
accepting default values also when no arguments are left away. This
can make argument meanings more clear than when only the value is
shown. Naming the required arguments this way is not possible,
though. Additionally, it is not possible to give first named arguments
and then varargs.</p>
<p>The biggest limitation of the name arguments functionality is that it
currently works only with <a class="reference internal" href="#creating-user-keywords">user keywords</a> and with <a class="reference internal" href="#using-test-libraries">library
keywords</a> implemented with Python that use either the <a class="reference internal" href="#creating-static-keywords">static library
API</a> or the <a class="reference internal" href="#hybrid-library-api">hybrid library API</a>. It is possible that support for
Java libraries and for the <a class="reference internal" href="#dynamic-library-api">dynamic library API</a> is added in the
future. Until that it is possible to create user keywords that wrap
the incompatible keywords.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">When the named argument syntax is used with user keywords,
the argument names are given without the <span class="var">${}</span>
decoration. For example, user keyword with arguments
<span class="code">${arg1}=default, ${arg2}=second</span> must be used like
<span class="code">arg2=override</span>.</p>
</div>
<p>The named argument syntax is used only when the part of the argument
before the equal sign matches the name of an argument with a
default value. This matching is started from the end of the given
argument list and stopped when there is no match. In those rare cases
when there are accidental matches, it is possible to use <span class="code">\</span>
to escape this syntax like <span class="code">nomatch\=here</span>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The named argument syntax is both case and space
sensitive. The former means that if you have an argument
<span class="code">arg</span>, you must use it like <span class="code">arg=&lt;value&gt;</span>, and
<span class="code">Arg=&lt;value&gt;</span> or <span class="code">ARG=&lt;value&gt;</span> do not work.  The
latter means that spaces are not allowed before the
<span class="code">=</span> sign, and possible spaces after it are considered
part of the default value itself.</p>
</div>
<p>The following example demonstrates using named arguments in different
scenarios, including in <a class="reference internal" href="#taking-test-libraries-into-use">test library imports</a>.</p>
<table border="1" class="example docutils">
<caption>Named argument example</caption>
<colgroup>
<col width="28%" />
<col width="24%" />
<col width="24%" />
<col width="24%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>Telnet</td>
<td>prompt=$</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="20%" />
<col width="25%" />
<col width="18%" />
<col width="18%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>Open connection</td>
<td>10.0.0.42</td>
<td>port=${25}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>List files</td>
<td>options=-lh</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>List files</td>
<td>path=/tmp</td>
<td>options=-l</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="17%" />
<col width="23%" />
<col width="28%" />
<col width="16%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>List files</td>
<td>[Arguments]</td>
<td>${path}=.</td>
<td>${options}=</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Execute command</td>
<td>ls ${options} ${path}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="arguments-embedded-to-keyword-names">
<h4><a class="toc-backref" href="#id348">Arguments embedded to keyword names</a></h4>
<p>A totally different approach to specify arguments is embedding them
into keyword names. This syntax is, at least currently, only supported
by <a class="reference internal" href="#embedding-arguments-into-keyword-name">user keywords</a>.</p>
</div>
</div>
<div class="section" id="test-case-name-and-documentation">
<h3><a class="toc-backref" href="#id349">2.2.3&nbsp;&nbsp;&nbsp;Test case name and documentation</a></h3>
<p>The test case name comes directly from the Test Case table: it is
exactly what is entered into the test case column. Test cases in one
test suite should have unique names.  Pertaining to this, you can also
use the <a class="reference internal" href="#automatic-variables">automatic variable</a> <span class="var">${TEST_NAME}</span> within the test
itself to refer to the test name. It is available whenever a test is
being executed, including all user keywords, as well as the test setup
and the test teardown.</p>
<p>The <span class="opt">[Documentation]</span> setting allows you to set a free
documentation for a test case. That text is shown in the command line
output, as well as the resulting test logs and test reports. If the
documentation is long, it can be <a class="reference internal" href="#dividing-test-data-to-several-rows">split into several cells</a> that are
catenated together with spaces. It is possible to use simple <a class="reference internal" href="#documentation-formatting">HTML
formatting</a> and <a class="reference internal" href="#variables">variables</a> can be used to make the documentation
dynamic. Possible non-existing variables in documentation are
just left unchanged starting from Robot Framework 2.1 version.</p>
<table border="1" class="example docutils">
<caption>Test case documentation examples</caption>
<colgroup>
<col width="17%" />
<col width="21%" />
<col width="27%" />
<col width="35%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Simple</td>
<td>[Documentation]</td>
<td>Simple documentation</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Splitting</td>
<td>[Documentation]</td>
<td>This documentation
is a bit longer and</td>
<td>it has been split into
several columns.</td>
</tr>
<tr><td>&nbsp;</td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Formatting</td>
<td>[Documentation]</td>
<td>*This is bold*,
_this italic_  and</td>
<td>here is a link:
http://robotframework.org</td>
</tr>
<tr><td>&nbsp;</td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Variables</td>
<td>[Documentation]</td>
<td>Executed at ${HOST}
by ${USER}</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>It is important that test cases have clear and descriptive names, and
in that case they normally do not need any documentation. If the logic
of the test case needs documenting, it is often a sign that keywords
in the test case need better names and they are to be enhanced,
instead of adding extra documentation. Finally, metadata, such as the
environment and user information in the last example above, is often
better specified using <a class="reference internal" href="#tagging-test-cases">tags</a>.</p>
</div>
<div class="section" id="tagging-test-cases">
<h3><a class="toc-backref" href="#id350">2.2.4&nbsp;&nbsp;&nbsp;Tagging test cases</a></h3>
<p>Using tags in Robot Framework is a simple, yet powerful mechanism for
classifying test cases. Tags are free text and they can be used at
least for the following purposes:</p>
<ul class="simple">
<li>Tags are shown in test <a class="reference internal" href="#report-file">reports</a>, <a class="reference internal" href="#log-file">logs</a> and, of course, in the test
data, so they provide metadata to test cases.</li>
<li><a class="reference internal" href="#configuring-statistics">Statistics</a> about test cases (total, passed, failed  are
automatically collected based on tags).</li>
<li>With tags, you can <a class="reference internal" href="#by-tag-names">include or exclude</a> test cases to be executed.</li>
<li>With tags, you can specify which test cases are considered <a class="reference internal" href="#setting-criticality">critical</a>.</li>
</ul>
<p>In this section it is only explained how to set tags for test
cases, and different ways to do it are listed below. These
approaches can naturally be used together.</p>
<dl class="docutils">
<dt><span class="opt">Force Tags</span> in the Setting table</dt>
<dd>All test cases in a test case file with this setting always get
specified tags. If it is used in the <cite>test suite initialization file</cite>,
all test cases in sub test suites get these tags.</dd>
<dt><span class="opt">Default Tags</span> in the Setting table</dt>
<dd>Test cases that do not have a <span class="opt">[Tags]</span> setting of their own
get these tags. Starting from Robot Framework version 2.5 default
tags are no longer supported in test suite initialization files.</dd>
<dt><span class="opt">[Tags]</span> in the Test Case table</dt>
<dd>A test case always gets these tags. Additionally, it does not get the
possible tags specified with <span class="opt">Default Tags</span>, so it is possible
to override the <span class="opt">Default Tags</span> by using empty value. Starting
from Robot Framework 2.5.6, is also possible to use value <span class="misc">NONE</span>
to override default tags.</dd>
<dt><span class="opt">--settag</span> command line option</dt>
<dd>All executed test cases get tags set with this option in addition
to tags they got elsewhere.</dd>
<dt><span class="name">Set Tags</span> and <span class="name">Remove Tags</span> keywords</dt>
<dd>These <a class="reference internal" href="#builtin-library">BuiltIn keywords</a> can be used to modify tags during the
test execution.</dd>
</dl>
<p>Tags are free text, but they are normalized so that they are converted
to lowercase and all spaces are removed. If a test case gets the same tag
several times, other occurrences than the first one are removed. Tags
can be created using variables, assuming that those variables exist.</p>
<table border="1" class="example docutils">
<caption>Tagging example</caption>
<colgroup>
<col width="33%" />
<col width="28%" />
<col width="19%" />
<col width="19%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Force Tags</td>
<td>req-42</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Default Tags</td>
<td>owner-john</td>
<td>smoke</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="30%" />
<col width="27%" />
<col width="21%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${HOST}</td>
<td>10.0.1.42</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="19%" />
<col width="22%" />
<col width="27%" />
<col width="31%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>No own tags</td>
<td>[Documentation]</td>
<td>This test has tags</td>
<td>owner-john, smoke,
req-42</td>
</tr>
<tr><td>&nbsp;</td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>With own tags</td>
<td>[Documentation]</td>
<td>This test has tags</td>
<td>not_ready, owner-mrx,
req-42</td>
</tr>
<tr><td>&nbsp;</td>
<td>[Tags]</td>
<td>owner-mrx</td>
<td>not_ready</td>
</tr>
<tr><td>&nbsp;</td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Own tags with
variables</td>
<td>[Documentation]</td>
<td>This test has tags</td>
<td>host-10.0.1.42, req-42</td>
</tr>
<tr><td>&nbsp;</td>
<td>[Tags]</td>
<td>host-${HOST}</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Empty own tags</td>
<td>[Documentation]</td>
<td>This test has tags</td>
<td>req-42</td>
</tr>
<tr><td>&nbsp;</td>
<td>[Tags]</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>No Operation</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Set Tags and
Remove Tags
Keywords</td>
<td>[Documentation]</td>
<td>This test has tags</td>
<td>mytag, owner-john</td>
</tr>
<tr><td>&nbsp;</td>
<td>Set Tags</td>
<td>mytag</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>Remove Tags</td>
<td>smoke</td>
<td>req-*</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="test-setup-and-teardown">
<h3><a class="toc-backref" href="#id351">2.2.5&nbsp;&nbsp;&nbsp;Test setup and teardown</a></h3>
<p>Robot Framework has similar test setup and teardown functionality as many
other test automation frameworks. In short, a test setup is something
that is executed before a test case, and a test teardown is executed
after a test case. In Robot Framework setups and teardowns are just
normal keywords with possible arguments.</p>
<p>Setup and teardown are always a single keyword. If they need to take care
of multiple separate tasks, it is possible to create higher-level <a class="reference internal" href="#creating-user-keywords">user
keywords</a> for that purpose. An alternative solution is executing multiple
keywords using the <a class="reference internal" href="#builtin-library">BuiltIn keyword</a> <span class="name">Run Keywords</span> that was added
in Robot Framework 2.5.</p>
<p>The test teardown is special in two ways. First of all, it is executed also
when a test case fails, so it can be used for clean-up activities that must be
done regardless of the test case status. Starting from Robot Framework 2.5, all
the keywords in the teardown are also executed even if one of them fails. This
<a class="reference internal" href="#continue-on-failure">continue on failure</a> functionality can be used also with normal keywords, but
inside teardowns it is on by default.</p>
<p>The easiest way to specify a setup or a teardown for test cases in a
test case file is using the <span class="opt">Test Setup</span> and <span class="opt">Test
Teardown</span> settings in the Setting table. Individual test cases can
also have their own setup or teardown. They are defined with the
<span class="opt">[Setup]</span> or <span class="opt">[Teardown]</span> settings in the test case
table and they override possible <span class="opt">Test Setup</span> and
<span class="opt">Test Teardown</span> settings. Having no keyword after a
<span class="opt">[Setup]</span> or <span class="opt">[Teardown]</span> setting means having no
setup or teardown. Starting from Robot Framework 2.5.6, it is also possible
to use value <span class="misc">NONE</span> to indicate that a test has no setup/teardown.</p>
<table border="1" class="example docutils">
<caption>Test setup and teardown examples</caption>
<colgroup>
<col width="30%" />
<col width="39%" />
<col width="16%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Test Setup</td>
<td>Open Application</td>
<td>App A</td>
<td>&nbsp;</td>
</tr>
<tr><td>Test Teardown</td>
<td>Close Application</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="26%" />
<col width="21%" />
<col width="27%" />
<col width="26%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Default values</td>
<td>[Documentation]</td>
<td>Setup and teardown</td>
<td>from setting table</td>
</tr>
<tr><td></td>
<td>Do Something</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Overridden setup</td>
<td>[Documentation]</td>
<td>Own setup, teardown</td>
<td>from setting table</td>
</tr>
<tr><td></td>
<td>[Setup]</td>
<td>Open Application</td>
<td>App B</td>
</tr>
<tr><td></td>
<td>Do Something</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>No teardown</td>
<td>[Documentation]</td>
<td>Default setup, no</td>
<td>teardown at all</td>
</tr>
<tr><td></td>
<td>Do Something</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Teardown]</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>No teardown 2</td>
<td>[Documentation]</td>
<td>Using special NONE,</td>
<td>works with 2.5.6</td>
</tr>
<tr><td></td>
<td>Do Something</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Teardown]</td>
<td>NONE</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Using variables</td>
<td>[Documentation]</td>
<td>Setup and teardown</td>
<td>given as variables</td>
</tr>
<tr><td></td>
<td>[Setup]</td>
<td>${SETUP}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Do Something</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Teardown]</td>
<td>${TEARDOWN}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>Often when creating use-case-like test cases, the terms <em>precondition</em>
and <em>postcondition</em> are preferred over the terms setup and
teardown. Robot Framework supports also this terminology, so that a
precondition is a synonym to a setup and a postcondition to a
teardown.</p>
<table border="1" class="tabular docutils">
<caption>Setup and teardown synonyms</caption>
<colgroup>
<col width="47%" />
<col width="53%" />
</colgroup>
<tbody valign="top">
<tr><td>Test Setup</td>
<td>Test Precondition</td>
</tr>
<tr><td>Test Teardown</td>
<td>Test Postcondition</td>
</tr>
<tr><td>[Setup]</td>
<td>[Precondition]</td>
</tr>
<tr><td>[Teardown]</td>
<td>[Postcondition]</td>
</tr>
</tbody>
</table>
<p>The name of the keyword to be executed as a setup or a teardown can be a
variable. This facilitates having different setups or teardowns in
different environments by giving the keyword name as a variable from
the command line.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#suite-setup-and-teardown">Test suites can have a setup and teardown of their
own</a>. A suite setup is executed before any test cases or sub test
suites in that test suite, and similarly a suite teardown is
executed after them.</p>
</div>
</div>
<div class="section" id="test-templates">
<h3><a class="toc-backref" href="#id352">2.2.6&nbsp;&nbsp;&nbsp;Test templates</a></h3>
<p>Test templates convert the normal <a class="reference internal" href="#keyword-driven-style">keyword-driven</a> test cases into
<a class="reference internal" href="#data-driven-style">data-driven</a> tests. Whereas the body of the normal test case is constructed
from keywords and their possible arguments, test cases with template define
only the arguments for the template keyword. This is illustrated by the
following example test cases that are functionally fully identical.</p>
<table border="1" class="example docutils">
<caption>Using test template</caption>
<colgroup>
<col width="29%" />
<col width="23%" />
<col width="25%" />
<col width="23%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Normal test case</td>
<td>Example keyword</td>
<td>first argument</td>
<td>second argument</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Templated test case</td>
<td>[Template]</td>
<td>Example keyword</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>first argument</td>
<td>second argument</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>As the example above illustrates, it is possible to specify the
template for an individual test case using the <span class="opt">[Template]</span>
setting. An alternative approach is using the <span class="opt">Test Template</span>
setting in the Setting table, in which case the template is applied
for all test cases in that test case file. The <span class="opt">[Template]</span>
setting overrides the possible template set in the Setting table, and
an empty value for <span class="opt">[Template]</span> means that the test has no
template even when <span class="opt">Test Template</span> is used. Starting from Robot Framework
2.5.6, it is also possible to use value <span class="misc">NONE</span> to indicate that a test
has no template.</p>
<p>If a templated test case has multiple data rows in its body, like in
the example below, the template is applied for all the rows. This
means that the same keyword is executed multiple times, once with data
on each row. Templated tests are also special so that all the rounds
are executed even if there are failures. It is possible to use this
kind of <a class="reference internal" href="#continue-on-failure">continue on failure</a> mode with normal tests too, but with
the templated tests the mode is on automatically.</p>
<table border="1" class="example docutils">
<caption>Using test template with multiple data rows</caption>
<colgroup>
<col width="29%" />
<col width="23%" />
<col width="25%" />
<col width="23%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Templated test case</td>
<td>[Template]</td>
<td>Example keyword</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>first round 1</td>
<td>first round 2</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>second round 1</td>
<td>second round 2</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>third round 1</td>
<td>third round 2</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>If templates are used with <a class="reference internal" href="#for-loops">for loops</a>, the template is applied for
all the steps inside the loop. The continue on failure mode is in use
also in this case, which means that all the steps are executed with
all the looped elements even if there are failures.</p>
<table border="1" class="example docutils">
<caption>Using test template with for loops</caption>
<colgroup>
<col width="26%" />
<col width="22%" />
<col width="22%" />
<col width="15%" />
<col width="15%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Template and for</td>
<td>[Template]</td>
<td>Example keyword</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>:FOR</td>
<td>${item}</td>
<td>IN</td>
<td>&#64;{ITEMS}</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>${item}</td>
<td>2nd arg</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>:FOR</td>
<td>${index}</td>
<td>IN RANGE</td>
<td>42</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>1st arg</td>
<td>${index}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>The main use case for test templates is reducing duplication with
data-driven tests. Instead of repeating the same keyword with all the
tests in a file, it is possible to use it only once in the Setting
table. This usage is illustrated more thoroughly in the next section.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Test templates is a new feature in Robot Framework 2.5.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">It is currently not possibly to specify the template keyword
using variables. This limitation may be lifted in the future
versions.</p>
</div>
</div>
<div class="section" id="different-test-case-styles">
<h3><a class="toc-backref" href="#id353">2.2.7&nbsp;&nbsp;&nbsp;Different test case styles</a></h3>
<p>There are several different ways in which test cases may be written. Test
cases that describe some kind of <em>workflow</em> may be written either in
keyword-driven or behavior-driven style. Data-driven style can be used to test
the same workflow with varying input data.</p>
<div class="section" id="keyword-driven-style">
<h4><a class="toc-backref" href="#id354">Keyword-driven style</a></h4>
<p>Workflow tests, such as the <span class="name">Valid Login</span> test described
<a class="reference internal" href="#example-tests">earlier</a>, are constructed from several keywords and their possible
arguments. Their normal structure is that first the system is taken
into the initial state (<span class="name">Open Login Page</span> in the <span class="name">Valid
Login</span> example), then something is done to the system (<span class="name">Input
Name</span>, <span class="name">Input Password</span>, <span class="name">Submit Credentials</span>), and
finally it is verified that the system behaved as expected
(<span class="name">Welcome Page Should Be Open</span>).</p>
</div>
<div class="section" id="data-driven-style">
<h4><a class="toc-backref" href="#id355">Data-driven style</a></h4>
<p>Another style to write test cases is the <em>data-driven</em> approach where
test cases use only one higher-level keyword, normally created as a
<a class="reference internal" href="#creating-user-keywords">user keyword</a>, that hides the actual test workflow. These tests are
very useful when there is a need to test the same scenario with
different input and/or output data. It would be possible to repeat the
same keyword with every test, but the <a class="reference internal" href="#test-templates">test template</a> functionality
allows specifying the keyword to use only once.</p>
<table border="1" class="example docutils">
<caption>Data-driven testing example</caption>
<colgroup>
<col width="31%" />
<col width="40%" />
<col width="15%" />
<col width="15%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Test Template</td>
<td>Login with invalid
credentials should fail</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="38%" />
<col width="22%" />
<col width="22%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">User Name</th>
<th class="head">Password</th>
<th class="head">&nbsp;</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Invalid User Name</td>
<td>invalid</td>
<td>${VALID
PASSWORD}</td>
<td>&nbsp;</td>
</tr>
<tr><td>Invalid Password</td>
<td>${VALID
USER}</td>
<td>invalid</td>
<td>&nbsp;</td>
</tr>
<tr><td>Invalid User Name
And Password</td>
<td>invalid</td>
<td>whatever</td>
<td>&nbsp;</td>
</tr>
<tr><td>Empty User Name</td>
<td>${EMPTY}</td>
<td>${VALID
PASSWORD}</td>
<td>&nbsp;</td>
</tr>
<tr><td>Empty Password</td>
<td>${VALID
USER}</td>
<td>${EMPTY}</td>
<td>&nbsp;</td>
</tr>
<tr><td>Empty User Name
And Password</td>
<td>${EMPTY}</td>
<td>${EMPTY}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>The above example has six separate tests, one for each invalid
user/password combination, and the example below illustrates how to
have only one test with all the combinations. When using <a class="reference internal" href="#test-templates">test
templates</a>, all the rounds in a test are executed even if there are
failures, so there is no real functional difference between these two
styles. In the above example separate combinations are named so it is
easier to see what they test, but having potentially large number of
these tests may mess-up statistics. Which style to use depends on the
context and personal preferences.</p>
<table border="1" class="example docutils">
<caption>Data-driven test with multiple data variations</caption>
<colgroup>
<col width="31%" />
<col width="24%" />
<col width="31%" />
<col width="15%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">User Name</th>
<th class="head">Password</th>
<th class="head">&nbsp;</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Invalid Password</td>
<td>[Template]</td>
<td>Login with invalid
credentials should
fail</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>invalid</td>
<td>${VALID PASSWORD}</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>${VALID USER}</td>
<td>invalid</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>invalid</td>
<td>whatever</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>${EMPTY}</td>
<td>${VALID PASSWORD}</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>${VALID USER}</td>
<td>${EMPTY}</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>${EMPTY}</td>
<td>${EMPTY}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p class="last">In both of the above examples, column headers have been
changed to match the data. This is possible because on the
first row other cells except the first one <a class="reference internal" href="#ignored-data">are ignored</a>.</p>
</div>
</div>
<div class="section" id="behavior-driven-style">
<h4><a class="toc-backref" href="#id356">Behavior-driven style</a></h4>
<p>It is also possible to write test cases as requirements that also non-technical
project stakeholders must understand. These <cite>Executable Requirements</cite> are a
corner stone of a process commonly called <a class="reference external" href="http://testobsessed.com/2008/12/08/acceptance-test-driven-development-atdd-an-overview">Acceptance Test Driven Development</a>
(ATDD).</p>
<p>One way to write these requirements/tests is <em>Given-When-Then</em> style
popularized by <a class="reference external" href="http://en.wikipedia.org/wiki/Behavior_Driven_Development">Behavior Driven Development</a> (BDD). When writing test cases in
this style, the initial state is usually expressed with a keyword starting with
word <span class="name">Given</span>, the actions are described with keyword starting with
<span class="name">When</span> and the expectations with a keyword starting with <span class="name">Then</span>.
Keyword starting with <span class="name">And</span> may be used if a step has more than one
action.</p>
<table border="1" class="example docutils">
<caption>Example test cases using behavior-driven style</caption>
<colgroup>
<col width="29%" />
<col width="71%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Step</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Valid Login</td>
<td>Given login page is open</td>
</tr>
<tr><td></td>
<td>When valid username and password are inserted</td>
</tr>
<tr><td></td>
<td>and credentials are submitted</td>
</tr>
<tr><td></td>
<td>Then welcome page should be open</td>
</tr>
</tbody>
</table>
<div class="section" id="ignoring-given-when-then-and-prefixes">
<h5>Ignoring <span class="name">Given/When/Then/And</span> prefixes</h5>
<p>Prefixes <span class="name">Given</span>, <span class="name">When</span>, <span class="name">Then</span> and <span class="name">And</span> are dropped
when matching keywords are searched, if no match with the full name is
found. This works for both user keywords and library keywords. For example,
<span class="name">Given login page is open</span> in the above example can be implemented as
user keyword either with or without the word <span class="name">Given</span>. Ignoring prefixes
also allows using the same keyword with different prefixes. For example
<span class="name">Welcome page should be open</span> could also used as <span class="name">And welcome page
should be open</span>.</p>
</div>
<div class="section" id="embedding-data-to-keywords">
<h5>Embedding data to keywords</h5>
<p>When writing concrete examples it is useful to be able pass actual data to
keyword implementations. User keywords support this by allowing <a class="reference internal" href="#embedding-arguments-into-keyword-name">embedding
arguments into keyword name</a>.</p>
</div>
</div>
</div>
</div>
<div class="section" id="creating-test-suites">
<h2><a class="toc-backref" href="#id321">2.3&nbsp;&nbsp;&nbsp;Creating test suites</a></h2>
<p>Robot Framework test cases are created in test case files, which can
be organized into directories. These files and directories create a
hierarchical test suite structure.</p>
<div class="contents local topic" id="id58">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#test-case-files" id="id357">2.3.1&nbsp;&nbsp;&nbsp;Test case files</a></li>
<li><a class="reference internal" href="#test-suite-directories" id="id358">2.3.2&nbsp;&nbsp;&nbsp;Test suite directories</a><ul>
<li><a class="reference internal" href="#warning-on-invalid-files" id="id359">Warning on invalid files</a></li>
<li><a class="reference internal" href="#initialization-files" id="id360">Initialization files</a></li>
</ul>
</li>
<li><a class="reference internal" href="#test-suite-name-and-documentation" id="id361">2.3.3&nbsp;&nbsp;&nbsp;Test suite name and documentation</a></li>
<li><a class="reference internal" href="#free-test-suite-metadata" id="id362">2.3.4&nbsp;&nbsp;&nbsp;Free test suite metadata</a></li>
<li><a class="reference internal" href="#suite-setup-and-teardown" id="id363">2.3.5&nbsp;&nbsp;&nbsp;Suite setup and teardown</a></li>
</ul>
</div>
<div class="section" id="test-case-files">
<h3><a class="toc-backref" href="#id357">2.3.1&nbsp;&nbsp;&nbsp;Test case files</a></h3>
<p>Robot Framework test cases <a class="reference internal" href="#test-case-syntax">are created</a> using test case tables in
test case files. Such a file automatically creates a test suite from
all the test cases it contains. There is no upper limit for how many
test cases there can be, but it is recommended to have less than ten,
unless the <a class="reference internal" href="#data-driven-style">data-driven approach</a> is used, where one test case consists of
only one high-level keyword.</p>
<p>The following settings in the Setting table can be used to customize the
test suite:</p>
<dl class="docutils">
<dt><span class="opt">Documentation</span></dt>
<dd>Used for specifying a <a class="reference internal" href="#test-suite-name-and-documentation">test suite documentation</a></dd>
<dt><span class="opt">Metadata</span></dt>
<dd>Used for setting <a class="reference internal" href="#free-test-suite-metadata">free test suite metadata</a> as name-value
pairs.</dd>
<dt><span class="opt">Suite Setup</span>, <span class="opt">Suite Teardown</span></dt>
<dd>Specify <a class="reference internal" href="#suite-setup-and-teardown">suite setup and teardown</a>. Have also synonyms
<span class="opt">Suite Precondition</span> and <span class="opt">Suite Postcondition</span>, respectively.</dd>
</dl>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">All setting names can optionally include a colon at the end, for
example <span class="opt">Documentation:</span>. This can make reading the settings easier
especially when using the plain text format. This is a
new feature in Robot Framework 2.5.5.</p>
</div>
</div>
<div class="section" id="test-suite-directories">
<h3><a class="toc-backref" href="#id358">2.3.2&nbsp;&nbsp;&nbsp;Test suite directories</a></h3>
<p>Test case files can be organized into directories, and these
directories create higher-level test suites. A test suite created from
a directory cannot have any test cases directly, but it contains
other test suites with test cases, instead. These directories can then be
placed into other directories creating an even higher-level suite. There
are no limits for the structure, so test cases can be organized
as needed.</p>
<p>When a test directory is executed, the files and directories it
contains are processed recursively as follows:</p>
<ul class="simple">
<li>Files and directories with names starting with a dot (<span class="path">.</span>) or an
underscore (<span class="path">_</span>) are ignored.</li>
<li>Directories with the name <span class="path">CVS</span> are ignored (case-sensitive).</li>
<li>Files not having one of the <a class="reference internal" href="#supported-file-formats">recognized extensions</a> (<span class="path">.html</span>,
<span class="path">.xhtml</span>, <span class="path">.htm</span>, <span class="path">.tsv</span>, <span class="path">.txt</span>, <span class="path">.rst</span>,
or <span class="path">.rest</span>) are ignored (case-insensitive).</li>
<li>Other files and directories are processed.</li>
</ul>
<p>If a file or directory that is processed does not contain any test
cases, it is silently ignored (a message is written to the <a class="reference internal" href="#system-log">syslog</a>)
and the processing continues.</p>
<div class="section" id="warning-on-invalid-files">
<h4><a class="toc-backref" href="#id359">Warning on invalid files</a></h4>
<p>Normally files that do not have a valid test case table are silently ignored
with a message written to the <a class="reference internal" href="#system-log">syslog</a>. As of Robot Framework 2.5.5 it is
possible to use a command line option <span class="opt">--warnonskippedfiles</span>, which turns
the message into a warning shown in <a class="reference internal" href="#errors-and-warnings-during-execution">test execution errors</a>.</p>
</div>
<div class="section" id="initialization-files">
<h4><a class="toc-backref" href="#id360">Initialization files</a></h4>
<p>A test suite created from a directory can have similar settings as a suite
created from a test case file. Because a directory alone cannot have that
kind of information, it must be placed into a special test suite initialization
file. Initialization files have the same structure and syntax as
test case files, except that they cannot have test case tables and not all
settings are supported.</p>
<p>An initialization file name must always be of the format <span class="path">__init__.ext</span>,
where the extension must match one of the <a class="reference internal" href="#supported-file-formats">supported file formats</a> (for example,
<span class="path">__init__.html</span> or <span class="path">__init__.txt</span>). The name format is borrowed
from Python, where files named in this manner denote that a directory is a module.</p>
<p>The main usage for initialization files is specifying test suite related
settings similarly as in <a class="reference internal" href="#test-case-files">test case files</a>, but setting some <a class="reference internal" href="#test-case-related-settings-in-the-setting-table">test case
related settings</a> is also possible. Variables and keywords created or
imported in initialization files <em>are not</em> available in the lower level
test suites, but <a class="reference internal" href="#resource-files">resource files</a> can be used if there is a need to
share them.</p>
<p>How to use different settings in the initialization files:</p>
<dl class="docutils">
<dt><span class="opt">Documentation</span>, <span class="opt">Metadata</span>, <span class="opt">Suite Setup</span>, <span class="opt">Suite Teardown</span></dt>
<dd>These test suite specific settings work the same way as in test case files.</dd>
<dt><span class="opt">Force Tags</span></dt>
<dd>Specified tags are unconditionally set to all test cases in all test case files
this directory contains directly or recursively.</dd>
<dt><span class="opt">Test Setup</span>, <span class="opt">Test Teardown</span>, <span class="opt">Test Timeout</span></dt>
<dd>Set the default value for test setup/teardown or test timeout to all test
cases this directory contains. Can be overridden on lower level.
Support for defining test timeout in initialization files was added in
Robot Framework 2.7.</dd>
<dt><span class="opt">Default Tags</span>, <span class="opt">Test Template</span></dt>
<dd>Not supported in initialization files.</dd>
</dl>
<table border="1" class="example docutils">
<caption>An example test suite initialization file</caption>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Documentation</td>
<td>Example suite</td>
<td>&nbsp;</td>
</tr>
<tr><td>Suite Setup</td>
<td>Do Something</td>
<td>${MESSAGE}</td>
</tr>
<tr><td>Force Tags</td>
<td>example</td>
<td>&nbsp;</td>
</tr>
<tr><td>Library</td>
<td>SomeLibrary</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${MESSAGE}</td>
<td>Hello, world!</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="22%" />
<col width="25%" />
<col width="27%" />
<col width="27%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Do Something</td>
<td>[Arguments]</td>
<td>${arg}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Some Keyword</td>
<td>${arg}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Another Keyword</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="test-suite-name-and-documentation">
<h3><a class="toc-backref" href="#id361">2.3.3&nbsp;&nbsp;&nbsp;Test suite name and documentation</a></h3>
<p>The test suite name is constructed from the file or directory name. The name
is created so that the extension is ignored, possible underscores are
replaced with spaces, and names fully in lower case are title cased. For
example, <span class="path">some_tests.html</span> becomes <span class="name">Some Tests</span> and
<span class="path">My_test_directory</span> becomes <span class="name">My test directory</span>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The rules for creating test suite names changed slightly in
Robot Framework 2.5.</p>
</div>
<p>The file or directory name can contain a prefix to control the <a class="reference internal" href="#execution-order">execution
order</a> of the suites. The prefix is separated from the base name by two
underscores and, when constructing the actual test suite name, both
the prefix and underscores are removed. For example files
<span class="path">01__some_tests.txt</span> and <span class="path">02__more_tests.txt</span> create test
suites <span class="name">Some Tests</span> and <span class="name">More Tests</span>, respectively, and
the former is executed before the latter.</p>
<p>The documentation for a test suite is set using the <span class="opt">Documentation</span>
setting in the Setting table. It can be used in test case files
or, with higher-level suites, in test suite initialization files. Test
suite documentation has exactly the same characteristics regarding to where
it is shown and how it can be created as <a class="reference internal" href="#test-case-name-and-documentation">test case
documentation</a>.</p>
<table border="1" class="example docutils">
<caption>Test suite documentation example</caption>
<colgroup>
<col width="16%" />
<col width="28%" />
<col width="28%" />
<col width="28%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Documentation</td>
<td>An example test suite</td>
<td>documentation with</td>
<td>*some* _formatting_.</td>
</tr>
<tr><td>...</td>
<td>See test documentation</td>
<td>for more documentation</td>
<td>examples.</td>
</tr>
</tbody>
</table>
<p>Both the name and documentation of the top-level test suite can be
overridden in test execution. This can be done with the command line
options <span class="opt">--name</span> and <span class="opt">--doc</span>, respectively, as
explained in section <a class="reference internal" href="#setting-metadata">Setting metadata</a>.</p>
</div>
<div class="section" id="free-test-suite-metadata">
<h3><a class="toc-backref" href="#id362">2.3.4&nbsp;&nbsp;&nbsp;Free test suite metadata</a></h3>
<p>Test suites can also have other metadata than the documentation. This metadata
is defined in the Setting table using the <span class="opt">Metadata</span> setting. Metadata
set in this manner is shown in test reports and logs.</p>
<p>The name and value for the metadata are located in the columns following
<span class="opt">Metadata</span>. The value is handled similarly as documentations, which means
that it can be <a class="reference internal" href="#dividing-test-data-to-several-rows">split into several cells</a> (joined together with spaces),
simple <a class="reference internal" href="#documentation-formatting">HTML formatting</a> works and even <a class="reference internal" href="#variables">variables</a> can be used.</p>
<table border="1" class="example docutils">
<caption>Metadata examples</caption>
<colgroup>
<col width="9%" />
<col width="12%" />
<col width="21%" />
<col width="26%" />
<col width="32%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Metadata</td>
<td>Version</td>
<td>2.0</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Metadata</td>
<td>More Info</td>
<td>For more information</td>
<td>about *Robot Framework*</td>
<td>see http://robotframework.org</td>
</tr>
<tr><td>Metadata</td>
<td>Executed At</td>
<td>${HOST}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>For top-level test suites, it is possible to set metadata also with the
<span class="opt">--metadata</span> command line option. This is discussed in more
detail in section <a class="reference internal" href="#setting-metadata">Setting metadata</a>.</p>
<p>Prior to Robot Framework 2.5 the free metadata was specified with syntax like
<span class="opt">Meta: &lt;name&gt;</span>, where <span class="opt">&lt;name&gt;</span> was the metadata name and the value
was defined in subsequent column. Robot Framework 2.5 still supports this old
format but it will be deprecated in the future.</p>
</div>
<div class="section" id="suite-setup-and-teardown">
<h3><a class="toc-backref" href="#id363">2.3.5&nbsp;&nbsp;&nbsp;Suite setup and teardown</a></h3>
<p>Not only <a class="reference internal" href="#test-setup-and-teardown">test cases</a> but also test suites can have a setup and
a teardown. A suite setup is executed before running any of the suite's
test cases or child test suites, and a test teardown is executed after
them. All test suites can have a setup and a teardown; with suites created
from a directory they must be specified in a <a class="reference internal" href="#initialization-files">test suite
initialization file</a>.</p>
<p>Similarly as with test cases, a suite setup and teardown are keywords
that may take arguments. They are defined in the Setting table with
<span class="opt">Suite Setup</span> and <span class="opt">Suite Teardown</span> settings,
respectively. They also have similar synonyms, <span class="opt">Suite
Precondition</span> and <span class="opt">Suite Postcondition</span>, as a test case setup
and teardown have. Keyword names and possible arguments are located in
the columns after the setting name.</p>
<p>If a suite setup fails, all test cases in it and its child test suites
are immediately assigned a fail status and they are not actually
executed. This makes suite setups ideal for checking preconditions
that must be met before running test cases is possible.</p>
<p>A suite teardown is normally used for cleaning up after all the test
cases have been executed. It is executed even if the setup of the same
suite fails. If the suite teardown fails, all test cases in the
suite are marked failed, regardless of their original execution status.
Starting from Robot Framework 2.5, all the keywords in suite teardowns
are executed even if one of them fails.</p>
<p>The name of the keyword to be executed as a setup or a teardown can be
a variable. This facilitates having different setups or teardowns
in different environments by giving the keyword name as a variable
from the command line.</p>
</div>
</div>
<div class="section" id="using-test-libraries">
<h2><a class="toc-backref" href="#id322">2.4&nbsp;&nbsp;&nbsp;Using test libraries</a></h2>
<p>Test libraries contain those lowest-level keywords, often called
<em>library keywords</em>, which actually interact with the system under
test. All test cases always use keywords from some library, often
through higher-level <a class="reference internal" href="#creating-user-keywords">user keywords</a>. This section explains how to
take test libraries into use and how to use the keywords they
provide. <a class="reference internal" href="#creating-test-libraries">Creating test libraries</a> is described in a separate
section.</p>
<div class="contents local topic" id="id65">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#taking-test-libraries-into-use" id="id364">2.4.1&nbsp;&nbsp;&nbsp;Taking test libraries into use</a><ul>
<li><a class="reference internal" href="#using-library-setting" id="id365">Using Library setting</a></li>
<li><a class="reference internal" href="#using-import-library-keyword" id="id366">Using Import Library keyword</a></li>
<li><a class="reference internal" href="#library-search-path" id="id367">Library search path</a></li>
<li><a class="reference internal" href="#using-physical-path-to-library" id="id368">Using physical path to library</a></li>
</ul>
</li>
<li><a class="reference internal" href="#setting-custom-name-to-test-library" id="id369">2.4.2&nbsp;&nbsp;&nbsp;Setting custom name to test library</a></li>
<li><a class="reference internal" href="#standard-libraries" id="id370">2.4.3&nbsp;&nbsp;&nbsp;Standard libraries</a><ul>
<li><a class="reference internal" href="#builtin-library" id="id371">BuiltIn library</a></li>
<li><a class="reference internal" href="#operatingsystem-library" id="id372">OperatingSystem library</a></li>
<li><a class="reference internal" href="#telnet-library" id="id373">Telnet library</a></li>
<li><a class="reference internal" href="#collections-library" id="id374">Collections library</a></li>
<li><a class="reference internal" href="#string-library" id="id375">String library</a></li>
<li><a class="reference internal" href="#dialogs-library" id="id376">Dialogs library</a></li>
<li><a class="reference internal" href="#screenshot-library" id="id377">Screenshot library</a></li>
<li><a class="reference internal" href="#remote-library" id="id378">Remote library</a></li>
</ul>
</li>
<li><a class="reference internal" href="#external-libraries" id="id379">2.4.4&nbsp;&nbsp;&nbsp;External libraries</a></li>
</ul>
</div>
<div class="section" id="taking-test-libraries-into-use">
<h3><a class="toc-backref" href="#id364">2.4.1&nbsp;&nbsp;&nbsp;Taking test libraries into use</a></h3>
<p>Instructions for taking test libraries into use are given in the
subsections below.</p>
<div class="section" id="using-library-setting">
<h4><a class="toc-backref" href="#id365">Using Library setting</a></h4>
<p>Test libraries are normally imported using the <span class="opt">Library</span>
setting in the Setting table and having the library name in the
subsequent column. The library name is case-sensitive (it is the name
of the module or class implementing the library and must be exactly
correct), but any spaces in it are ignored. With Python libraries in
modules or Java libraries in packages, the full name including the
module or package name must be used.</p>
<p>In those cases where the library needs arguments, they are listed in
the columns after the library name. It is possible to use default
values, variable number of arguments, and named arguments in test
library imports similarly as with <a class="reference internal" href="#using-arguments">arguments to keywords</a>.  Both the
library name and arguments can be set using variables.</p>
<table border="1" class="example docutils">
<caption>Importing test libraries</caption>
<colgroup>
<col width="21%" />
<col width="45%" />
<col width="17%" />
<col width="17%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>OperatingSystem</td>
<td></td>
<td></td>
</tr>
<tr><td>Library</td>
<td>com.company.TestLib</td>
<td></td>
<td></td>
</tr>
<tr><td>Library</td>
<td>MyLibrary</td>
<td>arg1</td>
<td>arg2</td>
</tr>
<tr><td>Library</td>
<td>${LIBRARY}</td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
<p>It is possible to import test libraries in <a class="reference internal" href="#test-case-files">test case files</a>,
<a class="reference internal" href="#resource-files">resource files</a> and <a class="reference internal" href="#initialization-files">test suite initialization files</a>. In all these
cases, all the keywords in the imported library are available in that
file. With resource files, those keywords are also available in other
files using them.</p>
</div>
<div class="section" id="using-import-library-keyword">
<h4><a class="toc-backref" href="#id366">Using Import Library keyword</a></h4>
<p>Another possibility to take a test library into use is using the
keyword <span class="name">Import Library</span> from the <a class="reference internal" href="#builtin-library">BuiltIn library</a>. This keyword
takes the library name and possible arguments similarly as the
<span class="opt">Library</span> setting. Keywords from the imported library are
available in the test suite where the <span class="name">Import Library</span> keyword was
used. This approach is useful in cases where the library is not
available when the test execution starts and only some other keywords
make it available.</p>
<table border="1" class="example docutils">
<caption>Using Import Library keyword</caption>
<colgroup>
<col width="19%" />
<col width="29%" />
<col width="17%" />
<col width="17%" />
<col width="17%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>Do Something</td>
<td></td>
<td></td>
<td></td>
</tr>
<tr><td></td>
<td>Import Library</td>
<td>MyLibrary</td>
<td>arg1</td>
<td>arg2</td>
</tr>
<tr><td></td>
<td>KW From Mylibrary</td>
<td></td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="library-search-path">
<h4><a class="toc-backref" href="#id367">Library search path</a></h4>
<p>The most common way to specify a test library to import is using its
name, like it has been done in all the examples in this section. In
these cases Robot Framework tries to find the class or module
implementing the library from the <em>library search path</em>. Basically,
this means that the library code and all its possible dependencies
must be in <span class="code">PYTHONPATH</span> or, when running tests on Jython, in a
<span class="code">CLASSPATH</span>. <a class="reference internal" href="#adjusting-library-search-path">Setting the library search path</a> is explained in
a section of its own. Libraries can also set the search path
automatically or have special instructions on how to do it. All
<a class="reference internal" href="#standard-libraries">standard libraries</a>, for example, are in the library search path
automatically.</p>
<p>The biggest benefit of this approach is that when the library search
path has been configured, often using a <a class="reference internal" href="#creating-start-up-scripts">custom start-up script</a>,
normal users do not need to think where libraries actually are
installed. The drawback is that getting your own, possible
very simple, libraries into the search path may require some
additional configuration.</p>
</div>
<div class="section" id="using-physical-path-to-library">
<h4><a class="toc-backref" href="#id368">Using physical path to library</a></h4>
<p>Another mechanism for specifying the library to import is using a
path to it in the file system. This path is considered relative to the
directory where current test data file is situated similarly as paths
to <a class="reference internal" href="#resource-and-variable-files">resource and variable files</a>. The main benefit of this approach
is that there is no need to configure the library search path.</p>
<p>If the library is a file, the path to it must contain extension. For
Python libraries the extension is naturally <span class="path">.py</span> and for Java
libraries it can either be <span class="path">.class</span> or <span class="path">.java</span>, but the
class file must always be available. If Python library is implemented
as a directory, the path to it must have a trailing forward slash
(<span class="path">/</span>). Following examples demonstrate these different
usages.</p>
<table border="1" class="example docutils">
<caption>Importing test libraries using physical paths to them</caption>
<colgroup>
<col width="17%" />
<col width="51%" />
<col width="15%" />
<col width="17%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>PythonLib.py</td>
<td></td>
<td></td>
</tr>
<tr><td>Library</td>
<td>/absolute/path/JavaLib.java</td>
<td></td>
<td></td>
</tr>
<tr><td>Library</td>
<td>relative/path/PythonDirLib/</td>
<td>possible</td>
<td>arguments</td>
</tr>
<tr><td>Library</td>
<td>${RESOURCES}/Example.class</td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
<p>A limitation of this approach is that libraries implemented as Python classes <a class="reference internal" href="#test-library-names">must
be in a module with the same name as the class</a>. Additionally, importing
libraries distributed in JAR or ZIP packages is not possible with this mechanism.</p>
</div>
</div>
<div class="section" id="setting-custom-name-to-test-library">
<h3><a class="toc-backref" href="#id369">2.4.2&nbsp;&nbsp;&nbsp;Setting custom name to test library</a></h3>
<p>The library name is shown in test logs before keyword names, and if
multiple keywords have the same name, they must be used so that the
<a class="reference internal" href="#handling-keywords-with-same-names">keyword name is prefixed with the library name</a>. The library name
is got normally from the module or class name implementing it, but
there are some situations where changing it is desirable:</p>
<ul class="simple">
<li>There is a need to import the same library several times with
different arguments. This is not possible otherwise.</li>
<li>The library name is inconveniently long. This can happen, for
example, if a Java library has a long package name.</li>
<li>You want to use variables to import different libraries in
different environments, but refer to them with the same name.</li>
<li>The library name is misleading or otherwise poor. In this case,
changing the actual name is, of course, a better solution.</li>
</ul>
<p>The basic syntax for specifying the new name is having the text
<span class="code">WITH NAME</span> (case-insensitive) after the library name and then
having the new name in the next cell. The specified name is shown in
logs and must be used in the test data when using keywords' full name
(<span class="name">LibraryName.Keyword Name</span>).</p>
<table border="1" class="example docutils">
<caption>Importing libraries with custom names</caption>
<colgroup>
<col width="20%" />
<col width="41%" />
<col width="20%" />
<col width="20%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>com.company.TestLib</td>
<td>WITH NAME</td>
<td>TestLib</td>
</tr>
<tr><td>Library</td>
<td>${LIBRARY}</td>
<td>WITH NAME</td>
<td>MyName</td>
</tr>
</tbody>
</table>
<p>Possible arguments to the library are placed into cells between the
original library name and the <span class="code">WITH NAME</span> text. The following example
illustrates how the same library can be imported several times with
different arguments:</p>
<table border="1" class="example docutils">
<caption>Importing the same library several times with a different name</caption>
<colgroup>
<col width="16%" />
<col width="19%" />
<col width="22%" />
<col width="12%" />
<col width="16%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>SomeLibrary</td>
<td>localhost</td>
<td>1234</td>
<td>WITH NAME</td>
<td>LocalLib</td>
</tr>
<tr><td>Library</td>
<td>SomeLibrary</td>
<td>server.domain</td>
<td>8080</td>
<td>WITH NAME</td>
<td>RemoteLib</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="20%" />
<col width="43%" />
<col width="20%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>My Test</td>
<td>LocalLib.Some Keyword</td>
<td>some arg</td>
<td>second arg</td>
</tr>
<tr><td></td>
<td>RemoteLib.Some Keyword</td>
<td>another arg</td>
<td>whatever</td>
</tr>
<tr><td></td>
<td>LocalLib.Another Keyword</td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
<p>Setting a custom name to a test library works both when importing a
library in the Setting table and when using the <span class="name">Import Library</span> keyword.</p>
</div>
<div class="section" id="standard-libraries">
<h3><a class="toc-backref" href="#id370">2.4.3&nbsp;&nbsp;&nbsp;Standard libraries</a></h3>
<p>Some test libraries are distributed with Robot Framework and these
libraries are called <em>standard libraries</em>. These are the available
standard libraries:</p>
<blockquote>
<ul class="simple">
<li><a class="reference internal" href="#builtin-library">BuiltIn</a></li>
<li><a class="reference internal" href="#operatingsystem-library">OperatingSystem</a></li>
<li><a class="reference internal" href="#telnet-library">Telnet</a></li>
<li><a class="reference internal" href="#collections-library">Collections</a></li>
<li><a class="reference internal" href="#string-library">String</a></li>
<li><a class="reference internal" href="#dialogs-library">Dialogs</a></li>
<li><a class="reference internal" href="#screenshot-library">Screenshot</a></li>
<li><a class="reference internal" href="#remote-library">Remote</a></li>
</ul>
</blockquote>
<p>The BuiltIn library is special, because it is taken into use
automatically and thus its keywords are always available. Other
standard libraries need to be imported in the same way as any other
libraries, but there is no need to install them. Additionally, they
work when running tests both with Python and Jython (with the
Screenshot library as an exception).</p>
<p>New standard libraries can, and will, be added in the future. If you
have an idea for a new standard library, or even have one that could
be incorporated immediately, please contact Robot Framework
developers. In general, a library is a good candidate to be added into
standard libraries if it is generic, works on both Python and Jython
without any external dependencies, and is adequately tested and
documented.</p>
<div class="section" id="builtin-library">
<h4><a class="toc-backref" href="#id371">BuiltIn library</a></h4>
<p>The BuiltIn library provides a set of generic keywords needed
often. It is imported automatically and thus always available. The
provided keywords can be used, for example, for verifications
(e.g. <span class="name">Should Be Equal</span>, <span class="name">Should Contain</span>), conversions
(e.g. <span class="name">Convert To Integer</span>) and for various other purposes
(e.g. <span class="name">Log</span>, <span class="name">Sleep</span>, <span class="name">Run Keyword If</span>, <span class="name">Set
Global Variable</span>).</p>
<p>The names of the keywords in the BuiltIn library have been renamed in
Robot Framework version 1.8. All the old keywords still work, but the
long names (the names visible in log files) of the keywords that are
deprecated begin with <span class="name">DeprecatedBuiltIn.</span> (for example,
<span class="name">DeprecatedBuiltIn.Equals</span>). It is highly recommended to use the
new names of the keywords as the old versions will be removed
altogether in the future.</p>
<p>For more information, see the <a class="reference external" href="../libraries/BuiltIn.html">BuiltIn library documentation</a>.</p>
</div>
<div class="section" id="operatingsystem-library">
<h4><a class="toc-backref" href="#id372">OperatingSystem library</a></h4>
<p>The OperatingSystem library enables various operating system related
tasks to be performed in the system where Robot Framework is
running. It can, among other things, execute commands
(e.g. <span class="name">Run</span>), create and remove files and directories
(e.g. <span class="name">Create File</span>, <span class="name">Remove Directory</span>), check whether
files or directories exists or contain something (e.g. <span class="name">File
Should Exist</span>, <span class="name">Directory Should Be Empty</span>) and manipulate
environment variables (e.g. <span class="name">Set Environment Variable</span>).</p>
<p>The names of the keywords in the OperatingSystem library have been
renamed in Robot Framework 1.8 similarly as the names of the BuiltIn
keywords.</p>
<p>For more information, see the <a class="reference external" href="../libraries/OperatingSystem.html">OperatingSystem library documentation</a>.</p>
</div>
<div class="section" id="telnet-library">
<h4><a class="toc-backref" href="#id373">Telnet library</a></h4>
<p>The Telnet library makes it possible to connect to Telnet servers and
execute commands on the opened connections.</p>
<p>For more information, see the <a class="reference external" href="../libraries/Telnet.html">Telnet library documentation</a>.</p>
</div>
<div class="section" id="collections-library">
<h4><a class="toc-backref" href="#id374">Collections library</a></h4>
<p>The Collections library provides a set of keywords for handling Python
lists and dictionaries. This library has keywords, for example, for
modifying and getting values from lists and dictionaries
(e.g. <span class="name">Append To List</span>, <span class="name">Get From Dictionary</span>) and for
verifying their contents (e.g. <span class="name">Lists Should Be Equal</span>,
<span class="name">Dictionary Should Contain Value</span>).</p>
<p>For more information, see the <a class="reference external" href="../libraries/Collections.html">Collections library documentation</a>.</p>
</div>
<div class="section" id="string-library">
<h4><a class="toc-backref" href="#id375">String library</a></h4>
<p>The String library enables manipulating strings (e.g. <span class="name">Replace
String With Regexp</span>, <span class="name">Split To Lines</span>) and verifying their
contents (e.g. <span class="name">Should Be String</span>).</p>
<p>For more information, see the <a class="reference external" href="../libraries/String.html">String library documentation</a>. This
library is new in Robot Framework 2.1.</p>
</div>
<div class="section" id="dialogs-library">
<h4><a class="toc-backref" href="#id376">Dialogs library</a></h4>
<p>The Dialogs library provides means for pausing the test execution and
getting input from users. The dialogs are slightly different depending
on are tests run on Python or Jython but they provide the same
functionality.</p>
<p>For more information, see the <a class="reference external" href="../libraries/Dialogs.html">Dialogs library documentation</a>. This
library is new in Robot Framework 2.1.</p>
</div>
<div class="section" id="screenshot-library">
<h4><a class="toc-backref" href="#id377">Screenshot library</a></h4>
<p>The Screenshot library has keywords to capture and store screenshots
of the whole desktop. This library is implemented with Java AWT APIs,
so it can be used only when running Robot Framework on Jython.</p>
<p>For more information, see the <a class="reference external" href="../libraries/Screenshot.html">Screenshot library documentation</a>.</p>
</div>
<div class="section" id="remote-library">
<h4><a class="toc-backref" href="#id378">Remote library</a></h4>
<p>The Remote library is totally different than the other standard
libraries. It does not have any keywords of its own but it works as a
proxy between Robot Framework and actual test library implementations.
These libraries can be running on other machines than the core
framework and can even be implemented using languages not supported by
Robot Framework natively.</p>
<p>See separate <a class="reference internal" href="#remote-library-interface">Remote library interface</a> section for more information
about the concept. This library is new in Robot Framework 2.1.</p>
</div>
</div>
<div class="section" id="external-libraries">
<h3><a class="toc-backref" href="#id379">2.4.4&nbsp;&nbsp;&nbsp;External libraries</a></h3>
<p>Any test library that is not one of the standard libraries is, by
definition, <em>an external library</em>. Robot Framework developers provide
some generic libraries, such as <a class="reference external" href="http://code.google.com/p/robotframework-seleniumlibrary">SeleniumLibrary</a> and <a class="reference external" href="http://code.google.com/p/robotframework-swinglibrary">SwingLibrary</a>,
which are not packaged with the framework itself, because they require
external dependencies. Generic libraries can also be provided by other
parties, and most teams have also some custom libraries only for
themselves.</p>
<p>Different external libraries can have a totally different mechanism
for installing and introducing them. Quite often they also require
some other dependencies to be installed separately. All libraries
should have clear instructions on this and preferably automate the
installation.</p>
<p>See <a class="reference internal" href="#creating-test-libraries">Creating test libraries</a> section for more information about how
to create new test libraries for your own or generic usage.</p>
</div>
</div>
<div class="section" id="variables">
<h2><a class="toc-backref" href="#id323">2.5&nbsp;&nbsp;&nbsp;Variables</a></h2>
<div class="contents local topic" id="id71">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#id72" id="id380">2.5.1&nbsp;&nbsp;&nbsp;Introduction</a></li>
<li><a class="reference internal" href="#variable-types" id="id381">2.5.2&nbsp;&nbsp;&nbsp;Variable types</a><ul>
<li><a class="reference internal" href="#scalar-variables" id="id382">Scalar variables</a></li>
<li><a class="reference internal" href="#list-variables" id="id383">List variables</a></li>
<li><a class="reference internal" href="#environment-variables" id="id384">Environment variables</a></li>
<li><a class="reference internal" href="#java-system-properties" id="id385">Java system properties</a></li>
</ul>
</li>
<li><a class="reference internal" href="#creating-variables" id="id386">2.5.3&nbsp;&nbsp;&nbsp;Creating variables</a><ul>
<li><a class="reference internal" href="#variable-table" id="id387">Variable table</a></li>
<li><a class="reference internal" href="#variable-file" id="id388">Variable file</a></li>
<li><a class="reference internal" href="#setting-variables-in-command-line" id="id389">Setting variables in command line</a></li>
<li><a class="reference internal" href="#return-values-from-keywords" id="id390">Return values from keywords</a></li>
<li><a class="reference internal" href="#using-built-in-set-test-suite-global-variable-keywords" id="id391">Using built-in <span class="name">Set Test/Suite/Global Variable</span> keywords</a></li>
</ul>
</li>
<li><a class="reference internal" href="#built-in-variables" id="id392">2.5.4&nbsp;&nbsp;&nbsp;Built-in variables</a><ul>
<li><a class="reference internal" href="#operating-system-variables" id="id393">Operating-system variables</a></li>
<li><a class="reference internal" href="#number-variables" id="id394">Number variables</a></li>
<li><a class="reference internal" href="#boolean-and-none-null-variables" id="id395">Boolean and None/null variables</a></li>
<li><a class="reference internal" href="#space-and-empty-variables" id="id396">Space and empty variables</a></li>
<li><a class="reference internal" href="#automatic-variables" id="id397">Automatic variables</a></li>
</ul>
</li>
<li><a class="reference internal" href="#variable-priorities-and-scopes" id="id398">2.5.5&nbsp;&nbsp;&nbsp;Variable priorities and scopes</a><ul>
<li><a class="reference internal" href="#variable-priorities" id="id399">Variable priorities</a></li>
<li><a class="reference internal" href="#variable-scopes" id="id400">Variable scopes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#advanced-variable-features" id="id401">2.5.6&nbsp;&nbsp;&nbsp;Advanced variable features</a><ul>
<li><a class="reference internal" href="#extended-variable-syntax" id="id402">Extended variable syntax</a></li>
<li><a class="reference internal" href="#variables-inside-variables" id="id403">Variables inside variables</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="id72">
<h3><a class="toc-backref" href="#id380">2.5.1&nbsp;&nbsp;&nbsp;Introduction</a></h3>
<p>Variables are an integral feature of Robot Framework, and they can be
used in most places in test data. Most commonly, they are used in
arguments for keywords in test case tables and keyword tables, but
also all settings allow variables in their values. A normal keyword
name <em>cannot</em> be specified with a variable, but the <a class="reference internal" href="#builtin-library">BuiltIn
keyword</a> <span class="name">Run Keyword</span> can be used to get the same effect.</p>
<p>Robot Framework itself has two kinds of variables, <a class="reference internal" href="#scalar-variables">scalars</a> and <a class="reference internal" href="#list-variables">lists</a>,
and they have the syntaxes <span class="var">${SCALAR}</span> and <span class="var">&#64;{LIST}</span>,
respectively. In addition to this, <a class="reference internal" href="#environment-variables">environment variables</a> can be used
directly with the syntax <span class="var">%{VARIABLE}</span>.</p>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">Using scalar variables and list variables with the same
base name, for example <span class="var">${VAR}</span> and <span class="var">&#64;{VAR}</span>,
has been deprecated in Robot Framework 2.5. For more
information, see <a class="reference external" href="http://code.google.com/p/robotframework/issues/detail?id=484">issue 484</a> in the issue tracker.</p>
</div>
<p>The use of variables is recommended in the following cases:</p>
<ul class="simple">
<li>When strings change often in the test data. With variables you only
need to make these changes in one place.</li>
<li>When creating system-independent and operating-system-independent
test data. Using variables instead of hard-coded strings eases that
considerably (for example, <span class="var">${RESOURCES}</span> instead of
<span class="code">c:\resources</span>, or <span class="var">${HOST}</span> instead of
<span class="code">10.0.0.1:8080</span>). Because variables can be <a class="reference internal" href="#setting-variables-in-command-line">set from the
command line</a> when tests are started, changing system-specific
variables is easy (for example, <span class="cli">--variable HOST:10.0.0.2:1234
--variable RESOURCES:/opt/resources</span>). This also facilitates
localization testing, which often involves running the same tests
with different strings.</li>
<li>When there is a need to have objects other than strings as arguments
for keywords.</li>
<li>When different keywords, even in different test libraries, need to
communicate. You can assign a return value from one keyword to a
variable and give that as an argument to another.</li>
<li>When values in the test data are long or otherwise complicated. For
example, <span class="var">${URL}</span> is shorter than
<span class="code">http://long.domain.name:8080/path/to/service?foo=1&amp;bar=2&amp;zap=42</span>.</li>
</ul>
<p>If a nonexistent variable is used in the test data, the keyword using
it fails. If the same syntax that is used for variables is needed as a
literal string, it must be <a class="reference internal" href="#escaping">escaped with a backslash</a> as in <span class="code">\${NAME}</span>.</p>
</div>
<div class="section" id="variable-types">
<h3><a class="toc-backref" href="#id381">2.5.2&nbsp;&nbsp;&nbsp;Variable types</a></h3>
<p>Different variable types are briefly described in this section. The
creation and usage of variables is described in more detail in the
following subsections.</p>
<p>Robot Framework variables, similarly as keywords, are
case-insensitive, and also spaces and underscores are
ignored. However, it is recommended to use all capital letters with
global variables (for example, <span class="var">${PATH}</span> or <span class="var">${TWO_WORDS}</span>)
and small letters with variables that are only available in certain
test cases or user keywords (for example, <span class="var">${my_var}</span> or
<span class="var">${myVar}</span>). Much more importantly, though, cases should be used
consistently.</p>
<p>Unlike in some programming languages where similar variable syntax is
used, curly braces (<span class="code">{</span> and <span class="code">}</span>) are mandatory in Robot Framework test
data. Basically, variable names can have any characters between the
curly braces. However, using only alphabetic characters from a to z,
numbers, underscore and space is recommended, and it is
even a requirement for using the <a class="reference internal" href="#extended-variable-syntax">extended variable syntax</a>.</p>
<div class="section" id="scalar-variables">
<h4><a class="toc-backref" href="#id382">Scalar variables</a></h4>
<p>When scalar variables are used in the test data, they are replaced
with the value they are assigned to. While scalar variables are most
commonly used for simple strings, you can assign any objects,
including lists, to them. The scalar variable syntax, for example
<span class="var">${NAME}</span>, should be familiar to most users, as it is also used,
for example, in shell scripts and Perl programming language.</p>
<p>The example below illustrates the usage of scalar variables. Assuming
that the variables <span class="var">${GREET}</span> and <span class="var">${NAME}</span> are available
and assigned to strings <span class="code">Hello</span> and <span class="code">world</span>, respectively,
both the example test cases are equivalent.</p>
<table border="1" class="example docutils">
<caption>Scalar variables with string values</caption>
<colgroup>
<col width="24%" />
<col width="16%" />
<col width="40%" />
<col width="20%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Strings</td>
<td>Log</td>
<td>Hello</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>Hello, world!!</td>
<td>&nbsp;</td>
</tr>
<tr><td>Variables</td>
<td>Log</td>
<td>${GREET}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>${GREET}, ${NAME}!!</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>When a scalar variable is used as the only value in a test data cell,
the scalar variable is replaced with the value it has. The value may
be any object. When a scalar variable is used in a test data cell with
anything else (constant strings or other variables), its value is
first converted into a Unicode string and then catenated to whatever is in
that cell. Converting the value into a string means that the object's
method <span class="code">__unicode__</span> (in Python, with <span class="code">__str__</span> as a fallback)
or <span class="code">toString</span> (in Java) is called.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Variable values are used as-is without conversions also when
passing arguments to keywords using the <a class="reference internal" href="#named-arguments">named arguments</a>
syntax like <span class="code">argname=${var}</span>.</p>
</div>
<p>The example below demonstrates the difference between having a
variable in a cell alone or with other content. First, let us assume
that we have a variable <span class="var">${STR}</span> set to a string <span class="code">Hello,
world!</span> and <span class="var">${OBJ}</span> set to an instance of the following Java
object:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyObj</span> <span class="o">{</span>

    <span class="kd">public</span> <span class="n">String</span> <span class="nf">toString</span><span class="o">()</span> <span class="o">{</span>
        <span class="k">return</span> <span class="s">&quot;Hi, tellus!&quot;</span><span class="o">;</span>
    <span class="o">}</span>
<span class="o">}</span>
</pre></div>
<p>With these two variables set, we then have the following test data:</p>
<table border="1" class="example docutils">
<caption>Scalar variables with objects as values</caption>
<colgroup>
<col width="24%" />
<col width="17%" />
<col width="37%" />
<col width="22%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Objects</td>
<td>KW 1</td>
<td>${STR}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>KW 2</td>
<td>${OBJ}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>KW 3</td>
<td>I said &quot;${STR}&quot;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>KW 4</td>
<td>You said &quot;${OBJ}&quot;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>Finally, when this test data is executed, different keywords receive
the arguments as explained below:</p>
<ul class="simple">
<li><span class="name">KW 1</span> gets a string <span class="code">Hello, world!</span></li>
<li><span class="name">KW 2</span> gets an object stored to variable <span class="var">${OBJ}</span></li>
<li><span class="name">KW 3</span> gets a string <span class="code">I said &quot;Hello, world!&quot;</span></li>
<li><span class="name">KW 4</span> gets a string <span class="code">You said &quot;Hi, tellus!&quot;</span></li>
</ul>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Converting variables to Unicode obviously fails if the variable
cannot be represented as Unicode. This can happen, for example,
if you try to use byte sequences as arguments to keywords so that
you catenate the values together like <span class="code">${byte1}${byte2}</span>.
A workaround is creating a variable that contains the whole value
and using it alone in the cell (e.g. <span class="code">${bytes}</span>) because then
the value is used as-is.</p>
</div>
</div>
<div class="section" id="list-variables">
<h4><a class="toc-backref" href="#id383">List variables</a></h4>
<p>List variables are compound variables that can have several
values assigned to them. In short, they are always lists and can
contain an unlimited number of entries (also empty lists are
possible). The main benefit of list variables is that they allow you
to assign a name for a larger data set. While list variables normally
contain only strings, other content is also possible.</p>
<p>When you use a list variable in test data, then the elements of the list
are inserted as new cells in the test data. Thus, if the list variable
contains two elements, the cell containing the list variable is turned
into two cells with the content of the list variable. Note that cells
with list variables should not contain other content. The list variable
syntax, <span class="var">&#64;{NAME}</span>, is borrowed from Perl.</p>
<p>Assuming that the list variable <span class="var">&#64;{USER}</span> is set to the value
<span class="code">['robot','secret']</span>, the following two test cases
are equivalent.</p>
<table border="1" class="example docutils">
<caption>Using list variables</caption>
<colgroup>
<col width="31%" />
<col width="19%" />
<col width="26%" />
<col width="24%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">User Name</th>
<th class="head">Password</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Strings</td>
<td>Login</td>
<td>robot</td>
<td>secret</td>
</tr>
<tr><td>List Variable</td>
<td>Login</td>
<td>&#64;{USER}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<div class="section" id="accessing-individual-list-variable-items">
<h5>Accessing individual list variable items</h5>
<p>It is also possible to access a certain value from the list variable
with the syntax <span class="var">&#64;{NAME}[i]</span>, where <span class="var">i</span> is the index of the
selected value. Indexes start from zero, and trying to access a value
with too large an index causes an error. List items accessed in this
manner can be used similarly as scalar variables:</p>
<table border="1" class="example docutils">
<caption>Accessing list variable items</caption>
<colgroup>
<col width="23%" />
<col width="26%" />
<col width="33%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Strings</td>
<td>Login</td>
<td>robot</td>
<td>secret</td>
</tr>
<tr><td></td>
<td>Title Should Be</td>
<td>Welcome robot!</td>
<td>&nbsp;</td>
</tr>
<tr><td>List Variable</td>
<td>Login</td>
<td>&#64;{USER}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Title Should Be</td>
<td>Welcome &#64;{USER}[0]!</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="using-list-variables-as-scalar-variables">
<h5>Using list variables as scalar variables</h5>
<p>It is possible to use list variables as scalar variables containing
lists simply by replacing <span class="var">&#64;</span> with <span class="var">$</span>. This makes it
possible to use list variables with list related keywords, for
example, from <a class="reference internal" href="#builtin-library">BuiltIn</a> and <a class="reference internal" href="#collections-library">Collections</a> libraries. This feature
works only if there is no scalar variable with same base name as the
list variable has. In these cases the scalar variable has precedence
and its value is used instead.</p>
<table border="1" class="example docutils">
<caption>Using list variables as scalars</caption>
<colgroup>
<col width="21%" />
<col width="25%" />
<col width="22%" />
<col width="16%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>&#64;{items} =</td>
<td>Create List</td>
<td>first</td>
<td>second</td>
</tr>
<tr><td></td>
<td>Length Should Be</td>
<td>${items}</td>
<td>2</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Append To List</td>
<td>${items}</td>
<td>third</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Length Should Be</td>
<td>${items}</td>
<td>3</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Remove From List</td>
<td>${items}</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Length Should Be</td>
<td>${items}</td>
<td>2</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log Many</td>
<td>&#64;{items}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="using-list-variables-with-settings">
<h5>Using list variables with settings</h5>
<p>List variables can be used only with some of the <a class="reference internal" href="#all-available-settings-in-test-data">settings</a>. They can
be used in arguments to imported libraries and variable files, but
library and variable file names themselves cannot be list
variables. Also with setups and teardowns list variable can not be used
as the name of the keyword, but can be used in arguments. With tag related
settings they can be used freely. Using scalar variables is possible in
those places where list variables are not supported.</p>
<table border="1" class="example docutils">
<caption>Using list variables with settings</caption>
<colgroup>
<col width="22%" />
<col width="25%" />
<col width="23%" />
<col width="31%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Settings</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Comment</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>ExampleLibrary</td>
<td>&#64;{LIB ARGS}</td>
<td># This works</td>
</tr>
<tr><td>Library</td>
<td>${LIBRARY}</td>
<td>&#64;{LIB ARGS}</td>
<td># This works</td>
</tr>
<tr><td>Library</td>
<td>&#64;{NAME AND ARGS}</td>
<td>&nbsp;</td>
<td># This does not work</td>
</tr>
<tr><td>Suite Setup</td>
<td>Some Keyword</td>
<td>&#64;{KW ARGS}</td>
<td># This works</td>
</tr>
<tr><td>Suite Setup</td>
<td>${KEYWORD}</td>
<td>&#64;{KW ARGS}</td>
<td># This works</td>
</tr>
<tr><td>Suite Setup</td>
<td>&#64;{KEYWORD}</td>
<td>&nbsp;</td>
<td># This does not work</td>
</tr>
<tr><td>Default Tags</td>
<td>&#64;{TAGS}</td>
<td>&nbsp;</td>
<td># This works</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="environment-variables">
<h4><a class="toc-backref" href="#id384">Environment variables</a></h4>
<p>Robot Framework allows using environment variables in the test
data using the syntax <span class="var">%{ENV_VAR_NAME}</span>. They are limited to string
values.</p>
<p>Environment variables set in the operating system before the test execution are
available during it, and it is possible to create new ones with the keyword
<span class="name">Set Environment Variable</span> or delete existing ones with the
keyword <span class="name">Delete Environment Variable</span>, both available in the
<a class="reference internal" href="#operatingsystem-library">OperatingSystem library</a>. Because environment variables are global,
environment variables set in one test case can be used in other test
cases executed after it. However, changes to environment variables are
not effective after the test execution.</p>
<table border="1" class="example docutils">
<caption>Using environment variables</caption>
<colgroup>
<col width="25%" />
<col width="15%" />
<col width="40%" />
<col width="19%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Env Variables</td>
<td>Log</td>
<td>Current user: %{USER}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Run</td>
<td>%{JAVA_HOME}${/}javac</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="java-system-properties">
<h4><a class="toc-backref" href="#id385">Java system properties</a></h4>
<p>When running tests with Jython, it is possible to access <a class="reference external" href="http://download.oracle.com/javase/tutorial/essential/environment/sysprop.html">Java system properties</a>
using same syntax as <a class="reference internal" href="#environment-variables">environment variables</a>. If an environment variable and a
system property with same name exist, the environment variable will be used.
Support for accessing Java system properties was added in Robot Framework 2.6.</p>
<table border="1" class="example docutils">
<caption>Using Java system properties</caption>
<colgroup>
<col width="23%" />
<col width="11%" />
<col width="53%" />
<col width="13%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>System Properties</td>
<td>Log</td>
<td>%{user.name} running tests on %{os.name}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="creating-variables">
<h3><a class="toc-backref" href="#id386">2.5.3&nbsp;&nbsp;&nbsp;Creating variables</a></h3>
<p>Variables can spring into existence from different sources as
described in the subsections below.</p>
<div class="section" id="variable-table">
<h4><a class="toc-backref" href="#id387">Variable table</a></h4>
<p>The most common source for variables are Variable tables in <a class="reference internal" href="#test-case-files">test case
files</a> and <a class="reference internal" href="#resource-files">resource files</a>. Variable tables are convenient, because they
allow creating variables in the same place as the rest of the test
data, and the needed syntax is very simple. Their main disadvantage is
that they only enable assigning variables into strings or a list of
strings. If other value types are needed, <a class="reference internal" href="#variable-files">variable files</a> are
probably a better option.</p>
<div class="section" id="creating-scalar-variables">
<h5>Creating scalar variables</h5>
<p>The simplest possible variable assignment is setting a string into a
scalar variable. This is done by giving the variable name (including
<span class="var">${}</span>) in the first column of the Variable table and the value in
the second one. If the second column is empty, an empty string is set
as a value. Also an already defined variable can be used in the value.</p>
<table border="1" class="example docutils">
<caption>Creating scalar variables</caption>
<colgroup>
<col width="31%" />
<col width="46%" />
<col width="23%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${NAME}</td>
<td>Robot Framework</td>
<td>&nbsp;</td>
</tr>
<tr><td>${VERSION}</td>
<td>2.0</td>
<td>&nbsp;</td>
</tr>
<tr><td>${ROBOT}</td>
<td>${NAME} ${VERSION}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>It is also possible, but not obligatory,
to use the equals sign <span class="code">=</span> after the variable name to make assigning
variables slightly more explicit.</p>
<table border="1" class="example docutils">
<caption>Creating scalar variables using the equals sign</caption>
<colgroup>
<col width="33%" />
<col width="42%" />
<col width="25%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${NAME} =</td>
<td>Robot Framework</td>
<td>&nbsp;</td>
</tr>
<tr><td>${VERSION} =</td>
<td>2.0</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="creating-list-variables">
<h5>Creating list variables</h5>
<p>Creating list variables is as easy as creating scalar variables. Again, the
variable name is in the first column of the Variable table and
values in the subsequent columns. A list variable can have any number
of values, starting from zero, and if many values are needed, they
can be <a class="reference internal" href="#dividing-test-data-to-several-rows">split into several rows</a>.</p>
<table border="1" class="example docutils">
<caption>Creating list variables</caption>
<colgroup>
<col width="31%" />
<col width="23%" />
<col width="23%" />
<col width="23%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>&#64;{NAMES}</td>
<td>Matti</td>
<td>Teppo</td>
<td>&nbsp;</td>
</tr>
<tr><td>&#64;{NAMES2}</td>
<td>&#64;{NAMES}</td>
<td>Seppo</td>
<td>&nbsp;</td>
</tr>
<tr><td>&#64;{NOTHING}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&#64;{MANY}</td>
<td>one</td>
<td>two</td>
<td>three</td>
</tr>
<tr><td>...</td>
<td>four</td>
<td>five</td>
<td>six</td>
</tr>
<tr><td>...</td>
<td>seven</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="variable-file">
<h4><a class="toc-backref" href="#id388">Variable file</a></h4>
<p>Variable files are the most powerful mechanism for creating different
kind of variables. It is possible to assign variables to any object
using them, and they also enable creating variables dynamically. The
variable file syntax and taking variable files into use is explained
in section <a class="reference internal" href="#resource-and-variable-files">Resource and variable files</a>.</p>
</div>
<div class="section" id="setting-variables-in-command-line">
<h4><a class="toc-backref" href="#id389">Setting variables in command line</a></h4>
<p>Variables can be set from the command line either individually with
the <span class="opt">--variable (-v)</span> option or using a variable file with the
<span class="opt">--variablefile (-V)</span> option. Variables set from the command line
are globally available for all executed test data files, and they also
override possible variables with the same names in the Variable table and in
variable files imported in the test data.</p>
<p>The syntax for setting individual variables is <span class="cli">--variable
name:value</span>, where <span class="cli">name</span> is the name of the variable without
<span class="var">${}</span> and <span class="cli">value</span> is its value. Several variables can be
set by using this option several times. Only scalar variables can be
set using this syntax and they can only get string values. Many
special characters are difficult to represent in the
command line, but they can be <a class="reference internal" href="#escaping-complicated-characters">escaped</a> with the <span class="opt">--escape</span>
option.</p>
<div class="highlight"><pre>--variable EXAMPLE:value
--variable HOST:localhost:7272 --variable USER:robot
--variable ESCAPED:Qquotes_and_spacesQ --escape quot:Q --escape space:_
</pre></div>
<p>In the examples above, variables are set so that</p>
<ul class="simple">
<li><span class="var">${EXAMPLE}</span> gets the value <span class="code">value</span></li>
<li><span class="var">${HOST}</span> and <span class="var">${USER}</span> get the values
<span class="code">localhost:7272</span> and <span class="code">robot</span></li>
<li><span class="var">${ESCAPED}</span> gets the value <span class="code">&quot;quotes and spaces&quot;</span></li>
</ul>
<p>The basic syntax for taking <a class="reference internal" href="#variable-files">variable files</a> into use from the command line
is <span class="cli">--variablefile path/to/variables.py</span>, and <a class="reference internal" href="#taking-variable-files-into-use">Taking variable files into
use</a> section has more details. What variables actually are created depends on
what variables there are in the referenced variable file.</p>
<p>If both variable files and individual variables are given from the command line,
the latter have <a class="reference internal" href="#variable-priorities-and-scopes">higher priority</a>.</p>
</div>
<div class="section" id="return-values-from-keywords">
<h4><a class="toc-backref" href="#id390">Return values from keywords</a></h4>
<p>Return values from keywords can also be set into variables. This
allows communication between different keywords even in different test
libraries. The syntax for a simple case is illustrated in the example below:</p>
<table border="1" class="example docutils">
<caption>Assigning values from keywords to variables</caption>
<colgroup>
<col width="24%" />
<col width="22%" />
<col width="27%" />
<col width="27%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Returning</td>
<td>${x} =</td>
<td>Get X</td>
<td>an argument</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>We got ${x}!</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>In the example above, the value returned by the <span class="name">Get X</span> keyword is
first set into the variable <span class="var">${x}</span> and then used by the <span class="name">Log</span>
keyword. This syntax works in all cases where a keywords returns
something, and the variable is set to whatever value returned by the
keyword. Having the equals sign <span class="code">=</span> after the variable name is
not obligatory, but recommended, because it makes the assignment
more explicit.</p>
<p>If a keyword returns a list, it is also possible to assign the return
value into several scalar variables and/or one list variable. Starting
from Robot Framework 2.5 this works with all list-like objects, but
prior to it only Python lists and tuples and Java arrays were supported.</p>
<table border="1" class="example docutils">
<caption>Assigning multiple values at once</caption>
<colgroup>
<col width="26%" />
<col width="21%" />
<col width="18%" />
<col width="18%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Return Multiple</td>
<td>${scalar} =</td>
<td>Get 3</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>${a}</td>
<td>${b}</td>
<td>${c} =</td>
<td>Get 3</td>
</tr>
<tr><td></td>
<td>${first}</td>
<td>&#64;{rest} =</td>
<td>Get 3</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&#64;{list} =</td>
<td>Get 3</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>Assuming that the keyword <span class="name">Get 3</span> returns a list
<span class="code">[1, 2, 3]</span>, the following variables are created:</p>
<ul class="simple">
<li><span class="var">${scalar}</span> with the value <span class="code">[1, 2, 3]</span></li>
<li><span class="var">${a}</span>, <span class="var">${b}</span> and <span class="var">${c}</span> with the values <span class="code">1</span>,
<span class="code">2</span>, and <span class="code">3</span>, respectively</li>
<li><span class="var">${first}</span> with the value <span class="code">1</span>, and <span class="var">&#64;{rest}</span> with the value
<span class="code">[2, 3]</span></li>
<li><span class="var">&#64;{list}</span> with the value <span class="code">[1, 2, 3]</span></li>
</ul>
<p>Variables set in this manner are otherwise similar to any other
variables, but they are available only within the scope of the test
case or keyword where they are created. Thus it is not possible, for
example, to set a variable in one test case and use it in another. This is
because, in general, automated test cases should not depend on each
other, and accidentally setting a variable that is used elsewhere
could cause hard-to-debug errors. If there is a genuine need for
setting a variable in one test case and using it in another, it is
possible to use built-in keywords as explained in the next section.</p>
</div>
<div class="section" id="using-built-in-set-test-suite-global-variable-keywords">
<h4><a class="toc-backref" href="#id391">Using built-in <span class="name">Set Test/Suite/Global Variable</span> keywords</a></h4>
<p>The <a class="reference internal" href="#builtin-library">BuiltIn library</a> has keywords <span class="name">Set Test Variable</span>,
<span class="name">Set Suite Variable</span> and <span class="name">Set Global Variable</span> which can
be used for setting variables dynamically during the test
execution. If a variable already exists within the new scope, its
value will be overwritten, and otherwise a new variable is created.</p>
<p>Variables set with <span class="name">Set Test Variable</span> keyword are available
everywhere within the scope of the currently executed test case. For
example, if you set a variable in a user keyword, it is available both
in the test case level and also in all other user keywords used in the
current test. Other test cases will not see variables set with this
keyword.</p>
<p>Variables set with <span class="name">Set Suite Variable</span> keyword are available
everywhere within the scope of the currently executed test
suite. Setting variables with this keyword thus has the same effect as
creating them using the <a class="reference internal" href="#variable-table">Variable table</a> in the test data file or
importing them from <a class="reference internal" href="#variable-files">variable files</a>. Other test suites, including
possible child test suites, will not see variables set with this
keyword.</p>
<p>Variables set with <span class="name">Set Global Variable</span> keyword are globally
available in all test cases and suites executed after setting
them. Setting variables with this keyword thus has the same effect as
<a class="reference internal" href="#setting-variables-in-command-line">creating from the command line</a> using the options <span class="opt">--variable</span> or
<span class="opt">--variablefile</span>. Because this keyword can change variables
everywhere, it should be used with care.</p>
</div>
</div>
<div class="section" id="built-in-variables">
<h3><a class="toc-backref" href="#id392">2.5.4&nbsp;&nbsp;&nbsp;Built-in variables</a></h3>
<p>Robot Framework provides some built-in variables that are available
automatically.</p>
<div class="section" id="operating-system-variables">
<h4><a class="toc-backref" href="#id393">Operating-system variables</a></h4>
<p>Built-in variables related to the operating system ease making the test data
operating-system-agnostic.</p>
<table border="1" class="tabular docutils">
<caption>Available operating-system-related built-in variables</caption>
<colgroup>
<col width="15%" />
<col width="85%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Explanation</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${CURDIR}</td>
<td>An absolute path to the directory where the test data
file is located. This variable is case-sensitive.</td>
</tr>
<tr><td>${TEMPDIR}</td>
<td>An absolute path to the system temporary directory. In UNIX-like
systems this is typically <span class="path">/tmp</span>, and in Windows
<span class="path">c:\Documents and Settings\&lt;user&gt;\Local Settings\Temp</span>.</td>
</tr>
<tr><td>${EXECDIR}</td>
<td>An absolute path to the directory where test execution was
started from. New in Robot Framework 2.1.</td>
</tr>
<tr><td>${/}</td>
<td>The system directory path separator. <span class="code">/</span> in UNIX-like
systems, <span class="code">\</span> in Windows.</td>
</tr>
<tr><td>${:}</td>
<td>The system path element separator. <span class="code">:</span> in UNIX-like
systems and <span class="code">;</span> in Windows.</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<caption>Using operating-system-related built-in variables</caption>
<colgroup>
<col width="14%" />
<col width="25%" />
<col width="24%" />
<col width="37%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>Create File</td>
<td>${CURDIR}${/}input.data</td>
<td>Some text here</td>
</tr>
<tr><td></td>
<td>Set Environment Variable</td>
<td>CLASSPATH</td>
<td>${TEMPDIR}${:}${TEMPDIR}${/}foo.jar</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="number-variables">
<h4><a class="toc-backref" href="#id394">Number variables</a></h4>
<p>The variable syntax can be used for creating both integers and
floating point numbers, as illustrated in the example below. This is
useful when a keyword expects to get an actual number, and not a
string that just looks like a number, as an argument.</p>
<table border="1" class="example docutils">
<caption>Using number variables</caption>
<colgroup>
<col width="12%" />
<col width="9%" />
<col width="12%" />
<col width="11%" />
<col width="56%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Comment</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example 1A</td>
<td>Connect</td>
<td>example.com</td>
<td>80</td>
<td># Connect gets two strings as arguments</td>
</tr>
<tr><td>Example 1B</td>
<td>Connect</td>
<td>example.com</td>
<td>${80}</td>
<td># Connect gets a string and an integer</td>
</tr>
<tr><td>Example 2</td>
<td>Do X</td>
<td>${3.14}</td>
<td>${-1e-4}</td>
<td># Do X gets floating point numbers 3.14 and -0.0001</td>
</tr>
</tbody>
</table>
<p>Starting from Robot Framework 2.6, it is possible to create integers
also from binary, octal, and hexadecimal values using <span class="var">0b</span>, <span class="var">0o</span>
and <span class="var">0x</span> prefixes, respectively. The syntax is case insetive.</p>
<table border="1" class="example docutils">
<caption>Using integer variables with base</caption>
<colgroup>
<col width="24%" />
<col width="33%" />
<col width="22%" />
<col width="22%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>Should Be Equal</td>
<td>${0b1011}</td>
<td>${11}</td>
</tr>
<tr><td></td>
<td>Should Be Equal</td>
<td>${0o10}</td>
<td>${8}</td>
</tr>
<tr><td></td>
<td>Should Be Equal</td>
<td>${0xff}</td>
<td>${255}</td>
</tr>
<tr><td></td>
<td>Should Be Equal</td>
<td>${0B1010}</td>
<td>${0XA}</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="boolean-and-none-null-variables">
<h4><a class="toc-backref" href="#id395">Boolean and None/null variables</a></h4>
<p>Also Boolean values and Python <span class="code">None</span> and Java <span class="code">null</span> can
be created using the variable syntax similarly as numbers.</p>
<table border="1" class="example docutils">
<caption>Using Boolean and None/null variables</caption>
<colgroup>
<col width="12%" />
<col width="16%" />
<col width="11%" />
<col width="11%" />
<col width="49%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Comment</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Boolean</td>
<td>Set Status</td>
<td>${true}</td>
<td>&nbsp;</td>
<td># Set Status gets Boolean true as an argument</td>
</tr>
<tr><td></td>
<td>Create Y</td>
<td>something</td>
<td>${false}</td>
<td># Create Y gets a string and Boolean false</td>
</tr>
<tr><td>None</td>
<td>Do XYZ</td>
<td>${None}</td>
<td>&nbsp;</td>
<td># Do XYZ gets Python None as an argument</td>
</tr>
<tr><td>Null</td>
<td>${ret} =</td>
<td>Get Value</td>
<td>arg</td>
<td># Checking that Get Value returns Java null</td>
</tr>
<tr><td></td>
<td>Should Be Equal</td>
<td>${ret}</td>
<td>${null}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>These variables are case-insensitive, so for example <span class="var">${True}</span> and
<span class="var">${true}</span> are equivalent. Additionally, <span class="var">${None}</span> and
<span class="var">${null}</span> are synonyms, because when running tests on the Jython
interpreter, Jython automatically converts <span class="code">None</span> and
<span class="code">null</span> to the correct format when necessary.</p>
</div>
<div class="section" id="space-and-empty-variables">
<h4><a class="toc-backref" href="#id396">Space and empty variables</a></h4>
<p>It is possible to create spaces and empty strings using variables
<span class="var">${SPACE}</span> and <span class="var">${EMPTY}</span>, respectively. These variables are
useful, for example, when there would otherwise be a need to <a class="reference internal" href="#escaping">escape
spaces or empty cells</a> with a backslash. If more than one space is
needed, it is possible to use the <a class="reference internal" href="#extended-variable-syntax">extended variable syntax</a> like
<span class="var">${SPACE * 5}</span>.  In the following example, <span class="name">Should Be
Equal</span> keyword gets identical arguments but those using variables are
easier to understand than those using backslashes.</p>
<table border="1" class="example docutils">
<caption>Using <span class="var">${SPACE}</span> and <span class="var">${EMPTY}</span></caption>
<colgroup>
<col width="17%" />
<col width="22%" />
<col width="21%" />
<col width="41%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>One Space</td>
<td>Should Be Equal</td>
<td>${SPACE}</td>
<td>\ \</td>
</tr>
<tr><td>Four Spaces</td>
<td>Should Be Equal</td>
<td>${SPACE * 4}</td>
<td>\ \ \ \ \</td>
</tr>
<tr><td>Ten Spaces</td>
<td>Should Be Equal</td>
<td>${SPACE * 10}</td>
<td>\ \ \ \ \ \ \ \ \ \ \</td>
</tr>
<tr><td>Quoted Space</td>
<td>Should Be Equal</td>
<td>&quot;${SPACE}&quot;</td>
<td>&quot; &quot;</td>
</tr>
<tr><td>Quoted Spaces</td>
<td>Should Be Equal</td>
<td>&quot;${SPACE * 2}&quot;</td>
<td>&quot; \ &quot;</td>
</tr>
<tr><td>Empty</td>
<td>Should Be Equal</td>
<td>${EMPTY}</td>
<td>\</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="automatic-variables">
<h4><a class="toc-backref" href="#id397">Automatic variables</a></h4>
<p>Some automatic variables can also be used in the test data. These
variables can have different values during the test execution and some
of them are not even available all the time.</p>
<table border="1" class="tabular docutils">
<caption>Available automatic variables</caption>
<colgroup>
<col width="24%" />
<col width="59%" />
<col width="17%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Explanation</th>
<th class="head">Available</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${TEST NAME}</td>
<td>The name of the current test case.</td>
<td>Test case</td>
</tr>
<tr><td>&#64;{TEST TAGS}</td>
<td>Contains the tags of the current test case in
alphabetical order.</td>
<td>Test case</td>
</tr>
<tr><td>${TEST STATUS}</td>
<td>The status of the current test case, either PASS or
FAIL.</td>
<td>Test teardown</td>
</tr>
<tr><td>${TEST MESSAGE}</td>
<td>The possible error message of the current test case.</td>
<td>Test teardown</td>
</tr>
<tr><td>${PREV TEST NAME}</td>
<td>The name of the previous test case, or an empty string
if no tests have been executed yet.</td>
<td>Everywhere</td>
</tr>
<tr><td>${PREV TEST STATUS}</td>
<td>The status of the previous test case: either PASS,
FAIL or an empty string when no tests have been
executed.</td>
<td>Everywhere</td>
</tr>
<tr><td>${PREV TEST MESSAGE}</td>
<td>The possible error message of the previous test case.</td>
<td>Everywhere</td>
</tr>
<tr><td>${SUITE NAME}</td>
<td>The full name of the current test suite.</td>
<td>Everywhere</td>
</tr>
<tr><td>${SUITE SOURCE}</td>
<td>An absolute path to the suite file or directory. New
in Robot Framework 2.5.</td>
<td>Everywhere</td>
</tr>
<tr><td>${SUITE STATUS}</td>
<td>The status of the current test case, either PASS or
FAIL.</td>
<td>Suite teardown</td>
</tr>
<tr><td>${SUITE MESSAGE}</td>
<td>The full message of the current test suite, including
statistics.</td>
<td>Suite teardown</td>
</tr>
<tr><td>${OUTPUT FILE}</td>
<td>An absolute path to the <a class="reference internal" href="#output-file">output file</a>.</td>
<td>Everywhere</td>
</tr>
<tr><td>${LOG FILE}</td>
<td>An absolute path to the <a class="reference internal" href="#log-file">log file</a> or string NONE
when no log file is created.</td>
<td>Everywhere</td>
</tr>
<tr><td>${REPORT FILE}</td>
<td>An absolute path to the <a class="reference internal" href="#report-file">report file</a> or string NONE
when no report is created.</td>
<td>Everywhere</td>
</tr>
<tr><td>${DEBUG FILE}</td>
<td>An absolute path to the <a class="reference internal" href="#debug-file">debug file</a> or string NONE
when no debug file is created.</td>
<td>Everywhere</td>
</tr>
<tr><td>${OUTPUT DIR}</td>
<td>An absolute path to the <a class="reference internal" href="#output-directory">output directory</a>.</td>
<td>Everywhere</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="variable-priorities-and-scopes">
<h3><a class="toc-backref" href="#id398">2.5.5&nbsp;&nbsp;&nbsp;Variable priorities and scopes</a></h3>
<p>Variables coming from different sources have different priorities and
are available in different scopes.</p>
<div class="section" id="variable-priorities">
<h4><a class="toc-backref" href="#id399">Variable priorities</a></h4>
<p><em>Variables from the command line</em></p>
<blockquote>
<p>Variables <a class="reference internal" href="#setting-variables-in-command-line">set in the command line</a> have the highest priority of all
variables that can be set before the actual test execution starts. They
override possible variables created in Variable tables in test case
files, as well as in resource and variable files imported in the
test data.</p>
<p>Individually set variables (<span class="opt">--variable</span> option) override the
variables set using <a class="reference internal" href="#variable-files">variable files</a> (<span class="opt">--variablefile</span> option).
If you specify same individual variable multiple times, the one specified
last will override earlier ones. This allows setting default values for
variables in a <a class="reference internal" href="#creating-start-up-scripts">start-up script</a> and overriding them from the command line.
Notice, though, that if multiple variable files have same variables, the
ones in the file specified first have the highest priority.</p>
</blockquote>
<p><em>Variable table in a test case file</em></p>
<blockquote>
<p>Variables created using the <a class="reference internal" href="#variable-table">Variable table</a> in a test case file
are available for all the test cases in that file. These variables
override possible variables with same names in imported resource and
variable files.</p>
<p>Variables created in the variable tables are available in all other tables
in the file where they are created. This means that they can be used also
in the Setting table, for example, for importing more variables from
resource and variable files.</p>
</blockquote>
<p><em>Imported resource and variable files</em></p>
<blockquote>
<p>Variables imported from the <a class="reference internal" href="#resource-and-variable-files">resource and variable files</a> have the
lowest priority of all variables created in the test data.
Variables from resource files and variable files have the same
priority. If several resource and/or variable file have same
variables, the ones in the file imported first are taken into use.</p>
<p>If a resource file imports resource files or variable files,
variables in its own Variable table have a higher priority than
variables it imports. All these variables are available for files that
import this resource file.</p>
<p>Note that variables imported from resource and variable files are not
available in the Variable table of the file that imports them. This
is due to the Variable table being processed before the Setting table
where the resource files and variable files are imported.</p>
</blockquote>
<p><em>Variables set during test execution</em></p>
<blockquote>
Variables set during the test execution either using <a class="reference internal" href="#return-values-from-keywords">return values
from keywords</a> or <a class="reference internal" href="#using-built-in-set-test-suite-global-variable-keywords">built-in keywords</a> <span class="name">Set
Test/Suite/Global Variable</span> always override possible existing
variables in the scope where they are set. In a sense they thus
have the highest priority, but on the other hand they do not affect
variables outside the scope they are defined.</blockquote>
<p><em>Built-in variables</em></p>
<blockquote>
<a class="reference internal" href="#built-in-variables">Built-in variables</a> like <span class="var">${TEMPDIR}</span> and <span class="var">${TEST_NAME}</span>
have the highest priority of all variables. They cannot be overridden
using Variable table or from command line, but even they can be reset during
the test execution. An exception to this rule are <a class="reference internal" href="#number-variables">number variables</a>, which
are resolved dynamically if no variable is found otherwise. They can thus be
overridden, but that is generally a bad idea. Additionally <span class="var">${CURDIR}</span>
is special because it is replaced already during the test data processing time.</blockquote>
</div>
<div class="section" id="variable-scopes">
<h4><a class="toc-backref" href="#id400">Variable scopes</a></h4>
<p>Depending on where and how they are created, variables can have a
global, test suite, test case or user keyword scope.</p>
<p><em>Global scope</em></p>
<blockquote>
<p>Global variables are available everywhere in the test data. These
variables are normally <a class="reference internal" href="#setting-variables-in-command-line">set from the command line</a> with the
<span class="opt">--variable</span> and <span class="opt">--variablefile</span> options, but it is also
possible to create new global variables or change the existing ones
with the <a class="reference internal" href="#builtin-library">BuiltIn keyword</a> <span class="name">Set Global Variable</span> anywhere in
the test data. Additionally also <a class="reference internal" href="#built-in-variables">built-in variables</a> are global.</p>
<p>It is recommended to use capital letters with all global variables.</p>
</blockquote>
<p><em>Test suite scope</em></p>
<blockquote>
<p>Variables with the test suite scope are available anywhere in the
test suite where they are defined or imported. They can be created
in Variable tables, imported from <a class="reference internal" href="#resource-and-variable-files">resource and variable files</a>,
or set during the test execution using the <a class="reference internal" href="#builtin-library">BuiltIn keyword</a>
<span class="name">Set Suite Variable</span>.</p>
<p>The test suite scope <em>is not recursive</em>, which means that variables
available in a higher-level test suite <em>are not available</em> in
lower-level suites. If necessary, <a class="reference internal" href="#resource-and-variable-files">resource and variable files</a> can
be used for sharing variables.</p>
<p>Since these variables can be considered global in the test suite where
they are used, it is recommended to use capital letters also with them.</p>
</blockquote>
<p><em>Test case scope</em></p>
<blockquote>
Variables created in test cases from the return values of keywords have a
test case scope and they are available only in that test
case. Another possibility to create them is using the <a class="reference internal" href="#builtin-library">BuiltIn keyword</a>
<span class="name">Set Test Variable</span> anywhere in that particular test case. Test
case variables are local and should use lower-case letters.</blockquote>
<p><em>User keyword scope</em></p>
<blockquote>
User keywords get their own variables from <a class="reference internal" href="#user-keyword-arguments">arguments passed to them</a>
and return values from the keywords they use. Also these variables
are local and should use lower-case letters.</blockquote>
</div>
</div>
<div class="section" id="advanced-variable-features">
<h3><a class="toc-backref" href="#id401">2.5.6&nbsp;&nbsp;&nbsp;Advanced variable features</a></h3>
<div class="section" id="extended-variable-syntax">
<h4><a class="toc-backref" href="#id402">Extended variable syntax</a></h4>
<p>Extended variable syntax can be used with objects set into scalar
variables. It allows accessing the attributes of the object (for example,
<span class="var">${obj.name}</span> or <span class="var">${obj.some_attr}</span>), and even calling
its methods (for example, <span class="var">${obj.get_name()}</span> or
<span class="var">${obj.getSomething('arg')}</span>).</p>
<p>Extended variable syntax is a powerful feature, but it should
be used with care. Accessing attributes is normally not a problem, on
the contrary, as one variable with an object having several
attributes is often better than having several variables. On the
other hand, calling methods, especially when they are used with
arguments, can make the test data complicated. If that happens,
it is recommended to move the code into a test library.</p>
<p>The most common usages of extended variable syntax are illustrated
in the example below. First assume that we have the following <a class="reference internal" href="#variable-file">variable file</a>
and test case:</p>
<div class="highlight"><pre><span class="k">class</span> <span class="nc">MyObject</span><span class="p">:</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>

    <span class="k">def</span> <span class="nf">greet</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">who</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">&#39;</span><span class="si">%s</span><span class="s"> says hello to </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">who</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span>

<span class="n">OBJECT</span> <span class="o">=</span> <span class="n">MyObject</span><span class="p">(</span><span class="s">&#39;Robot&#39;</span><span class="p">)</span>
<span class="n">DICTIONARY</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">1</span><span class="p">:</span> <span class="s">&#39;one&#39;</span><span class="p">,</span> <span class="mi">2</span><span class="p">:</span> <span class="s">&#39;two&#39;</span><span class="p">,</span> <span class="mi">3</span><span class="p">:</span> <span class="s">&#39;three&#39;</span><span class="p">}</span>
</pre></div>
<table border="1" class="example docutils">
<colgroup>
<col width="22%" />
<col width="16%" />
<col width="43%" />
<col width="20%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>KW 1</td>
<td>${OBJECT.name}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>KW 2</td>
<td>${OBJECT.greet('Fit')}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>KW 3</td>
<td>${DICTIONARY[2]}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>When this test data is executed, the keywords get the arguments as
explained below:</p>
<ul class="simple">
<li><span class="name">KW 1</span> gets string <span class="code">Robot</span></li>
<li><span class="name">KW 2</span> gets string <span class="code">Robot says hello to Fit</span></li>
<li><span class="name">KW 3</span> gets string <span class="code">two</span></li>
</ul>
<p>The extended variable syntax is evaluated in the following order:</p>
<ol class="arabic simple">
<li>The variable is searched using the full variable name. The extended
variable syntax is evaluated only if no matching variable
is found.</li>
<li>The real name of the base variable is created. The body of the name
consists of all the characters after <span class="var">${</span> until the first
occurrence of a non-alphanumeric character or a space (for example,
<span class="var">OBJECT</span> in <span class="var">${OBJECT.name}</span> and <span class="var">DICTIONARY</span> in
<span class="var">${DICTIONARY[2]}</span>).</li>
<li>A variable matching the body is searched. If there is no match, an
exception is raised and the test case fails.</li>
<li>The expression inside the curly brackets is evaluated as a Python
expression, so that the base variable name is replaced with its
value. If the evaluation fails because of an invalid syntax or that
the queried attribute does not exist, an exception is raised and
the test fails.</li>
<li>The whole extended variable is replaced with the value returned
from the evaluation.</li>
</ol>
<p>If the object that is used is implemented with Java, the extended
variable syntax allows you to access attributes using so-called bean
properties. In essence, this means that if you have an object with the
<span class="code">getName</span>  method set into a variable <span class="var">${OBJ}</span>, then the
syntax <span class="var">${OBJ.name}</span> is equivalent to, but clearer than
<span class="var">${OBJ.getName()}</span>. Thus the Python object used in the previous
example could be replaced with the following Java implementation:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyObject</span><span class="o">:</span>

    <span class="kd">private</span> <span class="n">String</span> <span class="n">name</span><span class="o">;</span>

    <span class="kd">public</span> <span class="nf">MyObject</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">)</span> <span class="o">{</span>
        <span class="n">name</span> <span class="o">=</span> <span class="n">name</span><span class="o">;</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="n">String</span> <span class="nf">getName</span><span class="o">()</span> <span class="o">{</span>
        <span class="k">return</span> <span class="n">name</span><span class="o">;</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="n">String</span> <span class="nf">greet</span><span class="o">(</span><span class="n">String</span> <span class="n">who</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">return</span> <span class="n">name</span> <span class="o">+</span> <span class="s">&quot; says hello to &quot;</span> <span class="o">+</span> <span class="n">who</span><span class="o">;</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="n">String</span> <span class="nf">toString</span><span class="o">()</span> <span class="o">{</span>
        <span class="k">return</span> <span class="n">name</span><span class="o">;</span>
    <span class="o">}</span>
<span class="o">}</span>
</pre></div>
<p>Many standard Python objects, including strings and numbers, have
methods that can be used with the extended variable syntax either
explicitly or implicitly. Sometimes this can be really useful and
reduce the need for setting temporary variables, but it is also easy
to overuse it and create really cryptic test data. Following examples
show few pretty good usages.</p>
<table border="1" class="example docutils">
<caption>Using methods of strings and numbers</caption>
<colgroup>
<col width="19%" />
<col width="21%" />
<col width="33%" />
<col width="26%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>String</td>
<td>${string} =</td>
<td>Set Variable</td>
<td>abc</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>${string.upper()}</td>
<td># Logs 'ABC'</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>${string * 2}</td>
<td># Logs 'abcabc'</td>
</tr>
<tr><td>Number</td>
<td>${number} =</td>
<td>Set Variable</td>
<td>${-2}</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>${number * 10}</td>
<td># Logs -20</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>${number.__abs__()}</td>
<td># Logs 2</td>
</tr>
</tbody>
</table>
<p>Note that even though <span class="code">abs(number)</span> is recommended over
<span class="code">number.__abs__()</span> in normal Python code, using
<span class="var">${abs(number)}</span> does not work. This is because the variable name
must be in the beginning of the extended syntax. Using <span class="code">__xxx__</span>
methods in the test data like this is already a bit questionable, and
it is normally better to move this kind of logic into test libraries.</p>
</div>
<div class="section" id="variables-inside-variables">
<h4><a class="toc-backref" href="#id403">Variables inside variables</a></h4>
<p>Variables are allowed also inside variables, and when this syntax is
used, variables are resolved from the inside out. For example, if you
have a variable <span class="var">${var${x}}</span>, then <span class="var">${x}</span> is resolved
first. If it has the value <span class="code">name</span>, the final value is then the
value of the variable <span class="var">${varname}</span>. There can be several nested
variables, but resolving the outermost fails, if any of them does not
exist.</p>
<p>In the example below, <span class="name">Do X</span> gets the value <span class="var">${JOHN HOME}</span>
or <span class="var">${JANE HOME}</span>, depending on if <span class="name">Get Name</span> returns
<span class="code">john</span> or <span class="code">jane</span>. If it returns something else, resolving
<span class="var">${${name} HOME}</span> fails.</p>
<table border="1" class="example docutils">
<caption>Using a variable inside another variable</caption>
<colgroup>
<col width="33%" />
<col width="28%" />
<col width="19%" />
<col width="19%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${JOHN HOME}</td>
<td>/home/john</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>${JANE HOME}</td>
<td>/home/jane</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="19%" />
<col width="21%" />
<col width="42%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>${name} =</td>
<td>Get Name</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Do X</td>
<td>${${name} HOME}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="section" id="creating-user-keywords">
<h2><a class="toc-backref" href="#id324">2.6&nbsp;&nbsp;&nbsp;Creating user keywords</a></h2>
<p>Keyword tables are used to create new higher-level keywords by
combining existing keywords together. These keywords are called <em>user
keywords</em> to differentiate them from lowest level <em>library keywords</em>
that are implemented in test libraries. The syntax for creating user
keywords is very close to the syntax for creating test cases, which
makes it easy to learn.</p>
<div class="contents local topic" id="id90">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#user-keyword-syntax" id="id404">2.6.1&nbsp;&nbsp;&nbsp;User keyword syntax</a><ul>
<li><a class="reference internal" href="#id91" id="id405">Basic syntax</a></li>
<li><a class="reference internal" href="#settings-in-the-keyword-table" id="id406">Settings in the Keyword table</a></li>
</ul>
</li>
<li><a class="reference internal" href="#user-keyword-name-and-documentation" id="id407">2.6.2&nbsp;&nbsp;&nbsp;User keyword name and documentation</a></li>
<li><a class="reference internal" href="#user-keyword-arguments" id="id408">2.6.3&nbsp;&nbsp;&nbsp;User keyword arguments</a><ul>
<li><a class="reference internal" href="#positional-arguments" id="id409">Positional arguments</a></li>
<li><a class="reference internal" href="#id95" id="id410">Default values</a></li>
<li><a class="reference internal" href="#id96" id="id411">Variable number of arguments</a></li>
</ul>
</li>
<li><a class="reference internal" href="#embedding-arguments-into-keyword-name" id="id412">2.6.4&nbsp;&nbsp;&nbsp;Embedding arguments into keyword name</a><ul>
<li><a class="reference internal" href="#id99" id="id413">Basic syntax</a></li>
<li><a class="reference internal" href="#embedded-arguments-matching-too-much" id="id414">Embedded arguments matching too much</a></li>
<li><a class="reference internal" href="#using-custom-regular-expressions" id="id415">Using custom regular expressions</a></li>
<li><a class="reference internal" href="#behavior-driven-development-example" id="id416">Behavior-driven development example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#user-keyword-return-values" id="id417">2.6.5&nbsp;&nbsp;&nbsp;User keyword return values</a></li>
<li><a class="reference internal" href="#keyword-teardown" id="id418">2.6.6&nbsp;&nbsp;&nbsp;Keyword teardown</a></li>
</ul>
</div>
<div class="section" id="user-keyword-syntax">
<h3><a class="toc-backref" href="#id404">2.6.1&nbsp;&nbsp;&nbsp;User keyword syntax</a></h3>
<div class="section" id="id91">
<h4><a class="toc-backref" href="#id405">Basic syntax</a></h4>
<p>In many ways, the overall user keyword syntax is identical to the
<a class="reference internal" href="#test-case-syntax">test case syntax</a>.  User keywords are created in keyword tables
which differ from test case tables only by the name that is used to
identify them. User keyword names are in the first column similarly as
test cases names. Also user keywords are created from keywords, either
from keywords in test libraries or other user keywords. Keyword names
are normally in the second column, but when setting variables from
keyword return values, they are in the subsequent columns.</p>
<table border="1" class="example docutils">
<caption>User keyword examples</caption>
<colgroup>
<col width="31%" />
<col width="23%" />
<col width="31%" />
<col width="15%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Open Login Page</td>
<td>Open Browser</td>
<td>http://host/login.html</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Title Should Be</td>
<td>Login Page</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Title Should Start With</td>
<td>[Arguments]</td>
<td>${expected}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>${title} =</td>
<td>Get Title</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Should Start With</td>
<td>${title}</td>
<td>${expected}</td>
</tr>
</tbody>
</table>
<p>Most user keywords take some arguments. This important feature is used
already in the second example above, and it is explained in detail
<a class="reference internal" href="#user-keyword-arguments">later in this section</a>, similarly as <a class="reference internal" href="#user-keyword-return-values">user keyword return
values</a>.</p>
<p>User keywords can be created in <a class="reference internal" href="#test-case-files">test case files</a>, <a class="reference internal" href="#resource-files">resource files</a>,
and <a class="reference internal" href="#initialization-files">test suite initialization files</a>. Keywords created in resource
files are available for files using them, whereas other keywords are
only available in the files where they are created.</p>
</div>
<div class="section" id="settings-in-the-keyword-table">
<h4><a class="toc-backref" href="#id406">Settings in the Keyword table</a></h4>
<p>User keywords can have similar settings as <a class="reference internal" href="#settings-in-the-test-case-table">test cases</a>, and they
have the same square bracket syntax separating them from keyword
names. All available settings are listed below and explained later in
this section.</p>
<dl class="docutils">
<dt><span class="opt">[Documentation]</span></dt>
<dd>Used for setting a <a class="reference internal" href="#user-keyword-name-and-documentation">user keyword documentation</a>.</dd>
<dt><span class="opt">[Arguments]</span></dt>
<dd>Specifies <a class="reference internal" href="#user-keyword-arguments">user keyword arguments</a>.</dd>
<dt><span class="opt">[Return]</span></dt>
<dd>Specifies <a class="reference internal" href="#user-keyword-return-values">user keyword return values</a>.</dd>
<dt><span class="opt">[Teardown]</span></dt>
<dd>Specify <a class="reference internal" href="#keyword-teardown">keyword teardown</a>. Available from Robot Framework 2.6 onwards.</dd>
<dt><span class="opt">[Timeout]</span></dt>
<dd>Sets the possible <a class="reference internal" href="#user-keyword-timeout">user keyword timeout</a>. <a class="reference internal" href="#timeouts">Timeouts</a> are discussed
in a section of their own.</dd>
</dl>
</div>
</div>
<div class="section" id="user-keyword-name-and-documentation">
<h3><a class="toc-backref" href="#id407">2.6.2&nbsp;&nbsp;&nbsp;User keyword name and documentation</a></h3>
<p>The user keyword name is defined in the first column of the user
keyword table. Of course, the name should be descriptive, and it is
acceptable to have quite long keyword names. Actually, when creating
use-case-like test cases, the highest-level keywords are often
formulated as sentences or even paragraphs.</p>
<p>User keywords can have a documentation that is set with the
<span class="opt">[Documentation]</span> setting, exactly as <a class="reference internal" href="#test-case-name-and-documentation">test case
documentation</a>. This setting documents the user keyword in the test
data. It is also shown in a more formal keyword documentation, which
the <a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> tool can create from <a class="reference internal" href="#resource-files">resource files</a>. Finally, the
first line of the documentation, everything until the first <span class="code">\n</span>
sequence, is shown as a keyword documentation in test logs.</p>
<p>Sometimes keywords need to be removed, replaced with new ones, or
deprecated for other reasons.  User keywords can be marked deprecated
by starting the documentation with <span class="code">*DEPRECATED*</span>, which will
cause a warning when the keyoword is used. For more information, see
<a class="reference internal" href="#deprecating-keywords">Deprecating keywords</a> section.</p>
</div>
<div class="section" id="user-keyword-arguments">
<h3><a class="toc-backref" href="#id408">2.6.3&nbsp;&nbsp;&nbsp;User keyword arguments</a></h3>
<p>Most user keywords need to take some arguments. The syntax for
specifying them is probably the most complicated feature normally
needed with Robot Framework, but even that is relatively easy,
particularly in most common cases. Arguments are normally specified with
the <span class="opt">[Arguments]</span> setting, and argument names use the same
syntax as <a class="reference internal" href="#variables">variables</a>, for example <span class="var">${arg}</span>.</p>
<div class="section" id="positional-arguments">
<h4><a class="toc-backref" href="#id409">Positional arguments</a></h4>
<p>The simplest way to specify arguments (apart from not having them at all)
is using only positional arguments. In most cases, this is all
that is needed.</p>
<p>The syntax is such that first the <span class="opt">[Arguments]</span> setting is
given and then argument names are defined in the subsequent
cells. Each argument is in its own cell, using the same syntax as with
variables. The keyword must be used with as many arguments as there
are argument names in its signature. The actual argument names do not
matter to the framework, but from users' perspective they should should
be as descriptive as possible. It is recommended
to use lower-case letters in variable names, either as
<span class="var">${my_arg}</span>, <span class="var">${my arg}</span> or <span class="var">${myArg}</span>.</p>
<table border="1" class="example docutils">
<caption>User keyword taking different number of arguments</caption>
<colgroup>
<col width="21%" />
<col width="16%" />
<col width="34%" />
<col width="14%" />
<col width="14%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>One Argument</td>
<td>[Arguments]</td>
<td>${arg_name}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>Got argument ${arg_name}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Three Arguments</td>
<td>[Arguments]</td>
<td>${arg1}</td>
<td>${arg2}</td>
<td>${arg3}</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>1st argument: ${arg1}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>2nd argument: ${arg2}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>3rd argument: ${arg3}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="id95">
<h4><a class="toc-backref" href="#id410">Default values</a></h4>
<p>Positional arguments are probably sufficient in most
situations. However, sometimes it is useful to be able to have a
keyword that takes a different number of arguments and has default
values for those that are not given. User keywords also allow this,
and the needed new syntax does not add very much to the already
discussed basic syntax. In short, default values are added to
arguments, so that first there is the equals sign (<span class="code">=</span>) and then
the value, for example <span class="var">${arg}=default</span>. There can be many
arguments with defaults, but they all must be given after the normal
positional arguments.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The syntax for default values is space sensitive. Spaces
before the <span class="code">=</span> sign are not allowed, and possible spaces
after it are considered part of the default value itself.</p>
</div>
<table border="1" class="example docutils">
<caption>User keyword with default values for arguments</caption>
<colgroup>
<col width="38%" />
<col width="17%" />
<col width="24%" />
<col width="22%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>One Argument With Default Value</td>
<td>[Arguments]</td>
<td>${arg}=default value</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Documentation]</td>
<td>This keyword takes</td>
<td>0-1 arguments</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>Got argument ${arg}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Two Arguments With Defaults</td>
<td>[Arguments]</td>
<td>${arg1}=default 1</td>
<td>${arg2}=default 2</td>
</tr>
<tr><td></td>
<td>[Documentation]</td>
<td>This keyword takes</td>
<td>0-2 arguments</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>1st argument ${arg1}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>2nd argument ${arg2}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>One Required And One With Default</td>
<td>[Arguments]</td>
<td>${required}</td>
<td>${optional}=default</td>
</tr>
<tr><td></td>
<td>[Documentation]</td>
<td>This keyword takes</td>
<td>1-2 arguments</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>Required: ${required}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>Optional: ${optional}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>When a keyword accepts several arguments with default values and only
some of them needs to be overridden, it is often handy to use the
<a class="reference internal" href="#named-arguments">named arguments</a> syntax. When this syntax is used with user
keywords, the arguments are specified without the <span class="var">${}</span>
decoration. For example, the second keyword above could be used like
below and <span class="var">${arg1}</span> would still get its default value.</p>
<table border="1" class="example docutils">
<caption>User keyword and named arguments syntax</caption>
<colgroup>
<col width="20%" />
<col width="41%" />
<col width="21%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>Two Arguments With Defaults</td>
<td>arg2=new value</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>As all Pythonistas must have already noticed, the syntax for
specifying default arguments is heavily inspired by Python syntax for
function default values.</p>
</div>
<div class="section" id="id96">
<h4><a class="toc-backref" href="#id411">Variable number of arguments</a></h4>
<p>Sometimes even default values are not enough and there is a need
for a keyword accepting any number of arguments. User keywords
support also this. All that is needed is having <a class="reference internal" href="#list-variables">list variable</a>
such as <span class="var">&#64;{varargs}</span> as the last argument in the keyword signature.
This syntax can be combined with the previously described positional
arguments and default values, and at the end the list variable gets all
the leftover arguments that do not match other arguments. The list
variable can thus have any number of items, even zero.</p>
<table border="1" class="example docutils">
<caption>User keywords accepting variable number of arguments</caption>
<colgroup>
<col width="36%" />
<col width="15%" />
<col width="22%" />
<col width="14%" />
<col width="14%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Any Number Of Arguments</td>
<td>[Arguments]</td>
<td>&#64;{varargs}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log Many</td>
<td>&#64;{varargs}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>One Or More Arguments</td>
<td>[Arguments]</td>
<td>${required}</td>
<td>&#64;{rest}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log Many</td>
<td>${required}</td>
<td>&#64;{rest}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Required, Default, Varargs</td>
<td>[Arguments]</td>
<td>${req}</td>
<td>${opt}=42</td>
<td>&#64;{others}</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>Required: ${req}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>Optional: ${opt}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>Others:</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>: FOR</td>
<td>${item}</td>
<td>IN</td>
<td>&#64;{others}</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Log</td>
<td>${item}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>Notice that if the last keyword above is used with more than one
argument, the second argument <span class="var">${opt}</span> always gets the given
value instead of the default value. This happens even if the given
value is empty. The last example also illustrates how a variable
number of arguments accepted by a user keyword can be used in a <a class="reference internal" href="#for-loops">for
loop</a>. This combination of two rather advanced functions can
sometimes be very useful.</p>
<p>Again, Pythonistas probably notice that the variable number of
arguments syntax is very close to the one in Python.</p>
</div>
</div>
<div class="section" id="embedding-arguments-into-keyword-name">
<h3><a class="toc-backref" href="#id412">2.6.4&nbsp;&nbsp;&nbsp;Embedding arguments into keyword name</a></h3>
<p>Robot Framework has also another approach to pass arguments to user
keywords than specifying them in cells after the keyword name as
explained in the previous section. This method is based on embedding
the arguments directly into the keyword name, and its main benefit is
making it easier to use real and clear sentences as keywords.</p>
<div class="section" id="id99">
<h4><a class="toc-backref" href="#id413">Basic syntax</a></h4>
<p>It has always been possible to use keywords like <span class="name">Select dog
from list</span> and <span class="name">Selects cat from list</span>, but all such keywords
must have been implemented separately. The idea of embedding arguments
into the keyword name is that all you need is a keyword with name like
<span class="name">Select ${animal} from list</span>.</p>
<table border="1" class="example docutils">
<caption>An example keyword with arguments embedded into its name</caption>
<colgroup>
<col width="37%" />
<col width="29%" />
<col width="18%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Select ${animal} from list</td>
<td>Open Page</td>
<td>Pet Selection</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Select Item From List</td>
<td>animal_list</td>
<td>${animal}</td>
</tr>
</tbody>
</table>
<p>Keywords using embedded arguments cannot take any &quot;normal&quot; arguments
(specified with <span class="opt">[Arguments]</span> setting) but otherwise they are
created just like other user keywords. The arguments used in the name
will naturally be available inside the keyword and they have different
value depending on how the keyword is called. For example,
<span class="var">${animal}</span> in the previous has value <span class="code">dog</span> if the keyword
is used like <span class="name">Select dog from list</span>. Obviously it is not
mandatory to use all these arguments inside the keyword, and they can
thus be used as wildcards.</p>
<p>These kind of keywords are also used the same way as other keywords
except that spaces and underscores are not ignored in their
names. They are, however, case-insensitive like other keywords. For
example, the keyword in the example above could be used like
<span class="name">select x from list</span>, but not like <span class="name">Select x fromlist</span>.</p>
<p>Embedded arguments do not support default values or variable number of
arguments like normal arguments do. Using variables when
calling these keywords is possible but that can reduce readability.
Notice also that embedded arguments only work with user keywords.</p>
</div>
<div class="section" id="embedded-arguments-matching-too-much">
<h4><a class="toc-backref" href="#id414">Embedded arguments matching too much</a></h4>
<p>One tricky part in using embedded arguments is making sure that the
values used when calling the keyword match the correct arguments. This
is a problem especially if there are multiple arguments and characters
separating them may also appear in the given values. For example,
keyword <span class="name">Select ${city} ${team}</span> does not work correctly if used
with city containing too parts like <span class="name">Select Los Angeles Lakers</span>.</p>
<p>An easy solution to this problem is quoting the arguments (e.g.
<span class="name">Select &quot;${city}&quot; &quot;${team}&quot;</span>) and using the keyword in quoted
format (e.g. <span class="name">Select &quot;Los Angeles&quot; &quot;Lakers&quot;</span>). This approach is
not enough to resolve all this kind of conflicts, though, but it is
still highly recommended because it makes arguments stand out from
rest of the keyword. A more powerful but also more complicated
solution, <a class="reference internal" href="#using-custom-regular-expressions">using custom regular expressions</a> when defining variables,
is explained in the next section. Finally, if things get complicated,
it might be a better idea to use normal positional arguments instead.</p>
<p>The problem of arguments matching too much occurs often when creating
keywords that <a class="reference internal" href="#ignoring-given-when-then-and-prefixes">ignore given/when/then/and prefixes</a> . For example,
<span class="name">${name} goes home</span> matches <span class="name">Given Janne goes home</span> so
that <span class="var">${name}</span> gets value <span class="code">Given Janne</span>. Quotes around the
argument, like in <span class="name">&quot;${name}&quot; goes home</span>, resolve this problem
easily.</p>
</div>
<div class="section" id="using-custom-regular-expressions">
<h4><a class="toc-backref" href="#id415">Using custom regular expressions</a></h4>
<p>When keywords with embedded arguments are called, the values are
matched internally using <a class="reference external" href="http://en.wikipedia.org/wiki/Regular_expression">regular expressions</a>
(regexps for short). The default logic goes so that every argument in
the name is replaced with a pattern <span class="code">.*?</span> that basically matches
any string. This logic works fairly well normally, but as just
discussed above, sometimes keywords <a class="reference internal" href="#embedded-arguments-matching-too-much">match more than
intended</a>. Quoting or otherwise separating arguments from the other
text can help but, for example, the test below fails because keyword
<span class="name">I execute &quot;ls&quot; with &quot;-lh&quot;</span> matches both of the defined
keywords.</p>
<table border="1" class="example docutils">
<caption>Embedded arguments match too much</caption>
<colgroup>
<col width="47%" />
<col width="53%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Step</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>I execute &quot;ls&quot;</td>
</tr>
<tr><td></td>
<td>I execute &quot;ls&quot; with &quot;-lh&quot;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="49%" />
<col width="15%" />
<col width="21%" />
<col width="15%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>I execute &quot;${cmd}&quot;</td>
<td>Run</td>
<td>${cmd}</td>
<td>&nbsp;</td>
</tr>
<tr><td>I execute &quot;${cmd}&quot; with &quot;${opts}&quot;</td>
<td>Run</td>
<td>${cmd} ${opts}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>A solution to this problem is using a custom regular expression that
makes sure that the keyword matches only what it should in that
particular context. To be able to use this feature, and to fully
understand the examples in this section, you need to understand at
least the basics of the regular expression syntax.</p>
<p>A custom embedded argument regular expression is defined after the
base name of the argument so that the argument and the regexp are
separated with a colon. For example, an argument that should match
only numbers can be defined like <span class="var">${arg:\d+}</span>. Using custom
regular expressions is illustrated by the examples below.</p>
<table border="1" class="example docutils">
<caption>Using custom regular expressions with embedded arguments</caption>
<colgroup>
<col width="47%" />
<col width="53%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Step</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>I execute &quot;ls&quot;</td>
</tr>
<tr><td></td>
<td>I execute &quot;ls&quot; with &quot;-lh&quot;</td>
</tr>
<tr><td></td>
<td>I type 1 + 2</td>
</tr>
<tr><td></td>
<td>I type 53 - 11</td>
</tr>
<tr><td></td>
<td>Today is 2011-06-27</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="48%" />
<col width="13%" />
<col width="16%" />
<col width="12%" />
<col width="11%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>I execute &quot;${cmd:[^&quot;]+}&quot;</td>
<td>Run</td>
<td>${cmd}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>I execute &quot;${cmd}&quot; with &quot;${opts}&quot;</td>
<td>Run</td>
<td>${cmd} ${opts}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>I type ${a:\d+} ${operator:[+-]} ${b:\d+}</td>
<td>Calculate</td>
<td>${a}</td>
<td>${operator}</td>
<td>${b}</td>
</tr>
<tr><td>Today is ${date:\d{4\}-\d{2\}-\d{2\}}</td>
<td>Log</td>
<td>${date}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>In the above example keyword <span class="name">I execute &quot;ls&quot; with &quot;-lh&quot;</span> matches
only <span class="name">I execute &quot;${cmd}&quot; with &quot;${opts}&quot;</span>. That is guaranteed
because the custom regular expression <span class="code">[^&quot;]+</span> in <span class="name">I execute
&quot;${cmd:[^&quot;]}&quot;</span> means that a matching argument cannot contain any
quotes. In this case there is no need to add custom regexps to the
other <span class="name">I execute</span> variant.</p>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p class="last">If you quote arguments, using regular expression <span class="code">[^&quot;]+</span>
guarantees that the argument matches only until the first
closing quote.</p>
</div>
<div class="section" id="supported-regular-expression-syntax">
<h5>Supported regular expression syntax</h5>
<p>Being implemented with Python, Robot Framework naturally uses Python's
<span class="name">re</span> module that has pretty standard <a class="reference external" href="http://docs.python.org/library/re.html">regular expressions
syntax</a>. This syntax is otherwise fully supported with embedded
arguments, but regexp extensions in format <span class="code">(?...)</span> cannot be
used. Notice also that matching embedded arguments is done
case-insensitively. If the regular expression syntax is invalid,
creating the keyword fails with an error visible in <a class="reference internal" href="#errors-and-warnings-during-execution">test execution
errors</a>.</p>
</div>
<div class="section" id="escaping-special-characters">
<h5>Escaping special characters</h5>
<p>There are some special characters that need to be escaped when used in
the custom embedded arguments regexp. First of all, possible closing
curly braces (<span class="code">}</span>) in the pattern need to be escaped with a
single backslash (<span class="code">\}</span>) because otherwise the argument would
end already there. Escaping closing burly braces is illustrated in the
previous example with keyword <span class="name">Today is
${date:\d{4\}-\d{2\}-\d{2\}}</span>.</p>
<p>Backslash (<span class="code">\</span>) is a special character in Python regular
expression syntax and thus needs to be escaped if you want to have a
literal backslash character. The safest escape sequence in this case
is four backslashes (<span class="code">\\\\</span>) but, depending on the next
character, also two backslashes may be enough.</p>
<p>Notice also that keyword names and possible embedded arguments in them
should <em>not</em> be escaped using the normal <a class="reference internal" href="#escaping">test data escaping
rules</a>. This means that, for example, backslashes in expressions
like <span class="var">${name:\w+}</span> should not be escaped.</p>
</div>
<div class="section" id="using-variables-with-custom-embedded-argument-regular-expressions">
<h5>Using variables with custom embedded argument regular expressions</h5>
<p>Whenever custom embedded argument regular expressions are used, Robot
Framework automatically enhances the specified regexps so that they
match variables in addition to the text matching the pattern. This
means that it is always possible to use variables with keywords having
embedded arguments. For example, the following test case would pass
using the keywords from the earlier example.</p>
<table border="1" class="example docutils">
<caption>Using variables with custom regular expressions</caption>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${DATE}</td>
<td>2011-06-27</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="47%" />
<col width="53%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Step</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>I type ${1} + ${2}</td>
</tr>
<tr><td></td>
<td>Today is ${DATE}</td>
</tr>
</tbody>
</table>
<p>A drawback of variables automatically matching custom regular
expressions is that it is possible that the value the keyword gets
does not actually match the specified regexp. For example, variable
<span class="var">${DATE}</span> in the above example could contain any value and
<span class="name">Today is ${DATE}</span> would still match the same keyword.</p>
</div>
</div>
<div class="section" id="behavior-driven-development-example">
<h4><a class="toc-backref" href="#id416">Behavior-driven development example</a></h4>
<p>The biggest benefit of having arguments as part of the keyword name is that it
makes it easier to use higher-level sentence-like keywords when writing test
cases in <a class="reference internal" href="#behavior-driven-style">behavior-driven style</a>. The example below illustrates this. Notice
also that prefixes <span class="name">Given</span>, <span class="name">When</span> and <span class="name">Then</span> are <a class="reference internal" href="#ignoring-given-when-then-and-prefixes">left out
of the keyword definitions</a>.</p>
<table border="1" class="example docutils">
<caption>Embedded arguments used by BDD style tests</caption>
<colgroup>
<col width="47%" />
<col width="53%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Step</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Add two numbers</td>
<td>Given I have Calculator open</td>
</tr>
<tr><td></td>
<td>When I add 2 and 40</td>
</tr>
<tr><td></td>
<td>Then result should be 42</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
</tr>
<tr><td>Add negative numbers</td>
<td>Given I have Calculator open</td>
</tr>
<tr><td></td>
<td>When I add 1 and -2</td>
</tr>
<tr><td></td>
<td>Then result should be -1</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="49%" />
<col width="19%" />
<col width="16%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>I have ${program} open</td>
<td>Start Program</td>
<td>${program}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>I add ${number 1} and ${number 2}</td>
<td>Input Number</td>
<td>${number 1}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Push Button</td>
<td>+</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Input Number</td>
<td>${number 2}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Push Button</td>
<td>=</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Result should be ${expected}</td>
<td>${result} =</td>
<td>Get Result</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Should Be Equal</td>
<td>${result}</td>
<td>${expected}</td>
</tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Embedded arguments feature in Robot Framework is inspired by
how <cite>step definitions</cite> are created in a popular BDD tool
called <a class="reference external" href="http://cukes.info">Cucumber</a>.</p>
</div>
</div>
</div>
<div class="section" id="user-keyword-return-values">
<h3><a class="toc-backref" href="#id417">2.6.5&nbsp;&nbsp;&nbsp;User keyword return values</a></h3>
<p>Similarly as library keywords, also user keywords can return
values. Return values are defined with the <span class="opt">[Return]</span>
setting. The values can then be <a class="reference internal" href="#return-values-from-keywords">assigned to variables</a> in test
cases or other user keywords.</p>
<p>In a typical case, a user keyword returns one value and it can be set
to a scalar variable. This is done by having the return value in the
next cell after the <span class="opt">[Return]</span> setting. User keywords can
also return several values, which can then be assigned into several
scalar variables at once, to a list variable, or to scalar variables
and a list variable. Several values can be returned simply by
specifying those values in different cells after the
<span class="opt">[Return]</span> setting.</p>
<table border="1" class="example docutils">
<caption>User keywords returning values</caption>
<colgroup>
<col width="19%" />
<col width="14%" />
<col width="22%" />
<col width="22%" />
<col width="22%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>One Return Value</td>
<td>${ret} =</td>
<td>Return One Value</td>
<td>argument</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Some Keyword</td>
<td>${ret}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Multiple Values</td>
<td>${a}</td>
<td>${b}</td>
<td>${c} =</td>
<td>Return Three Values</td>
</tr>
<tr><td></td>
<td>&#64;{list} =</td>
<td>Return Three Values</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>${scalar}</td>
<td>&#64;{rest} =</td>
<td>Return Three Values</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="29%" />
<col width="18%" />
<col width="21%" />
<col width="17%" />
<col width="15%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Return One Value</td>
<td>[Arguments]</td>
<td>${arg}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Do Something</td>
<td>${arg}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>${value} =</td>
<td>Get Some Value</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Return]</td>
<td>${value}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Return Three Values</td>
<td>[Return]</td>
<td>foo</td>
<td>bar</td>
<td>zap</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="keyword-teardown">
<h3><a class="toc-backref" href="#id418">2.6.6&nbsp;&nbsp;&nbsp;Keyword teardown</a></h3>
<p>Starting from Robot Framework 2.6, also user keywords may have a teardown.
It is defined using <span class="opt">[Teardown]</span> setting.</p>
<p>Keyword teardown works much in the same way as a <a class="reference internal" href="#test-setup-and-teardown">test case
teardown</a>.  Most importantly, the teardown is always a single
keyword, although it can be another user keyword, and it gets executed
also when the user keyword fails. In addition, all steps of the
teardown are executed even if one of them fails. However, a failure in
keyword teardown will fail the test case and subsequent steps in the
test are not run. The name of the keyword to be executed as a teardown
can also be a variable.</p>
<table border="1" class="example docutils">
<colgroup>
<col width="26%" />
<col width="21%" />
<col width="27%" />
<col width="26%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">User Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>With Teardown</td>
<td>Do Something</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Teardown]</td>
<td>Log</td>
<td>keyword teardown</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Using variables</td>
<td>[Documentation]</td>
<td>Teardown given as</td>
<td>variable</td>
</tr>
<tr><td></td>
<td>Do Something</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Teardown]</td>
<td>${TEARDOWN}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="resource-and-variable-files">
<h2><a class="toc-backref" href="#id325">2.7&nbsp;&nbsp;&nbsp;Resource and variable files</a></h2>
<p>User keywords and variables in <a class="reference internal" href="#test-case-files">test case files</a> and <a class="reference internal" href="#initialization-files">test suite
initialization files</a> can only be used in files where they are
created, but <em>resource files</em> provide a mechanism for sharing them. Since
the resource file structure is very close to test case files, it is
easy to create them.</p>
<p><em>Variable files</em> provide a powerful mechanism for creating and sharing
variables. For example, they allow values other than strings and
enable creating variables dynamically. Their flexibility comes from
the fact that they are created using Python code, which also makes
them somewhat more complicated than <a class="reference internal" href="#variable-table">Variable tables</a>.</p>
<div class="contents local topic" id="id110">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#resource-files" id="id419">2.7.1&nbsp;&nbsp;&nbsp;Resource files</a><ul>
<li><a class="reference internal" href="#taking-resource-files-into-use" id="id420">Taking resource files into use</a></li>
<li><a class="reference internal" href="#resource-file-structure" id="id421">Resource file structure</a></li>
<li><a class="reference internal" href="#documenting-resource-files" id="id422">Documenting resource files</a></li>
<li><a class="reference internal" href="#example-resource-file" id="id423">Example resource file</a></li>
</ul>
</li>
<li><a class="reference internal" href="#variable-files" id="id424">2.7.2&nbsp;&nbsp;&nbsp;Variable files</a><ul>
<li><a class="reference internal" href="#taking-variable-files-into-use" id="id425">Taking variable files into use</a></li>
<li><a class="reference internal" href="#creating-variables-directly" id="id426">Creating variables directly</a></li>
<li><a class="reference internal" href="#getting-variables-from-a-special-function" id="id427">Getting variables from a special function</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="resource-files">
<h3><a class="toc-backref" href="#id419">2.7.1&nbsp;&nbsp;&nbsp;Resource files</a></h3>
<div class="section" id="taking-resource-files-into-use">
<h4><a class="toc-backref" href="#id420">Taking resource files into use</a></h4>
<p>Resource files are imported using the <span class="opt">Resource</span> setting in the
Settings table. The path to the resource file is given in the cell
after the setting name.</p>
<p>If the path is given in an absolute format, it is used directly. In other
cases, the resource file is first searched relatively to the directory
where the importing file is located. If the file is not found there,
it is then searched from the directories in PYTHONPATH. The path can
contain variables, and it is recommended to use them to make paths
system-independent (for example, <span class="path">${RESOURCES}/login_resources.html</span> or
<span class="path">${RESOURCE_PATH}</span>). Additionally, slashes (&quot;/&quot;) in the path
are automatically changed to backslashes (&quot;\&quot;) on Windows.</p>
<table border="1" class="example docutils">
<caption>Importing resource files</caption>
<colgroup>
<col width="23%" />
<col width="59%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Resource</td>
<td>myresources.html</td>
<td>&nbsp;</td>
</tr>
<tr><td>Resource</td>
<td>../data/resources.html</td>
<td>&nbsp;</td>
</tr>
<tr><td>Resource</td>
<td>${RESOURCES}/common.tsv</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>The user keywords and variables defined in a resource file are
available in the file that takes that resource file into
use. Similarly available are also all keywords and variables from the
libraries, resource files and variable files imported by the said
resource file.</p>
</div>
<div class="section" id="resource-file-structure">
<h4><a class="toc-backref" href="#id421">Resource file structure</a></h4>
<p>The higher-level structure of resource files is the same as that of
test case files otherwise, but, of course, they cannot contain Test
Case tables. Additionally, the Setting table in resource files can
contain only import settings (<span class="opt">Library</span>, <span class="opt">Resource</span>,
<span class="opt">Variables</span>) and <span class="opt">Documentation</span>. The Variable table and
Keyword table are used exactly the same way as in test case files.</p>
<p>If several resource files have a user keyword with the same name, they
must be used so that the <a class="reference internal" href="#handling-keywords-with-same-names">keyword name is prefixed with the resource
file name</a> without the extension (for example, <span class="name">myresources.Some
Keyword</span> and <span class="name">common.Some Keyword</span>). Moreover, if several resource
files contain the same variable, the one that is imported first is
taken into use.</p>
</div>
<div class="section" id="documenting-resource-files">
<h4><a class="toc-backref" href="#id422">Documenting resource files</a></h4>
<p>Keywords created in a resource file can be <a class="reference internal" href="#user-keyword-name-and-documentation">documented</a> using
<span class="opt">[Documentation]</span> setting. Starting from Robot Framework 2.1 also
the resource file itself can have <span class="opt">Documentation</span> in the Setting
table similarly as <a class="reference internal" href="#test-suite-name-and-documentation">test suites</a>.</p>
<p>Both <a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> and <a class="reference internal" href="#test-data-editing-tool-ride">RIDE</a> use these documentations, and they
are naturally available for anyone opening resource files.  The
first line of the documentation of a keyword is logged when it is run,
but otherwise resource file documentations are ignored during the test
execution.</p>
</div>
<div class="section" id="example-resource-file">
<h4><a class="toc-backref" href="#id423">Example resource file</a></h4>
<table border="1" class="example docutils">
<colgroup>
<col width="25%" />
<col width="47%" />
<col width="14%" />
<col width="14%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Documentation</td>
<td>An example resource file</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Library</td>
<td>SeleniumLibrary</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Resource</td>
<td>${RESOURCES}/common.html</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="25%" />
<col width="50%" />
<col width="13%" />
<col width="13%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${HOST}</td>
<td>localhost:7272</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>${LOGIN_URL}</td>
<td>http://${HOST}/</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>${WELCOME_URL}</td>
<td>http://${HOST}/welcome.html</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>${BROWSER}</td>
<td>Firefox</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="23%" />
<col width="23%" />
<col width="21%" />
<col width="21%" />
<col width="12%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Open Login Page</td>
<td>[Documentation]</td>
<td>Opens browser</td>
<td>to login page</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Open Browser</td>
<td>${LOGIN_URL}</td>
<td>${BROWSER}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Title Should Be</td>
<td>Login Page</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Input Name</td>
<td>[Arguments]</td>
<td>${name}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Input Text</td>
<td>username_field</td>
<td>${name}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Input Password</td>
<td>[Arguments]</td>
<td>${password}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Input Text</td>
<td>password_field</td>
<td>${password}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="variable-files">
<h3><a class="toc-backref" href="#id424">2.7.2&nbsp;&nbsp;&nbsp;Variable files</a></h3>
<p>Variable files contain <a class="reference internal" href="#variables">variables</a> that can be used in test
data. Variables can also be created using variable tables or set from
the command line, but variable files allow creating them dynamically
and their variables can contain any objects.</p>
<p>Variable files are created using the <a class="reference external" href="http://www.python.org/">Python</a> code, and technically they are
Python modules. There are two different possibilities for creating
variables:</p>
<dl class="docutils">
<dt><a class="reference internal" href="#creating-variables-directly">Creating variables directly</a></dt>
<dd>Variables are specified as module attributes. In simple cases, the
syntax is so simple that no real programming is needed. For example,
<span class="code">MY_VAR = 'my value'</span> creates a variable
<span class="var">${MY_VAR}</span> with the specified text as the value.</dd>
<dt><a class="reference internal" href="#getting-variables-from-a-special-function">Getting variables from a special function</a></dt>
<dd>Alternatively, variable files can have a special <span class="code">get_variables</span>
(or <span class="code">getVariables</span>) method that returns variables as either a Python dictionary or a Java Map.
This method can even take arguments, which makes this
approach quite flexible.</dd>
</dl>
<div class="section" id="taking-variable-files-into-use">
<h4><a class="toc-backref" href="#id425">Taking variable files into use</a></h4>
<div class="section" id="setting-table">
<h5>Setting table</h5>
<p>All test data files can import variables using the
<span class="opt">Variables</span> setting in the Setting table, in the same way as
<a class="reference internal" href="#taking-resource-files-into-use">resource files are imported</a> using the <span class="opt">Resource</span>
setting. Similarly to resource files, the path to the imported
variable file is considered relative to the directory where the
importing file is, and if not found, it is searched from the
directories in PYTHONPATH. The path can also contain variables, and
slashes are converted to backslashes on Windows. If an <a class="reference internal" href="#getting-variables-from-a-special-function">argument file takes
arguments</a>, they are specified in the cells after the path and also they
can contain variables.</p>
<table border="1" class="example docutils">
<caption>Importing a variable file</caption>
<colgroup>
<col width="20%" />
<col width="50%" />
<col width="15%" />
<col width="15%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Variables</td>
<td>myvariables.py</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Variables</td>
<td>../data/variables.py</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Variables</td>
<td>${RESOURCES}/common.py</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Variables</td>
<td>taking_arguments.py</td>
<td>arg1</td>
<td>${ARG2}</td>
</tr>
</tbody>
</table>
<p>All variables from a variable file are available in the test data file
that imports it. If several variable files are imported and they
contain a variable with the same name, the one in the earliest imported file is
taken into use. Additionally, variables created in Variable tables and
set from the command line override variables from variable files.</p>
</div>
<div class="section" id="command-line">
<h5>Command line</h5>
<p>Another way to take variable files into use is using the command line option
<span class="opt">--variablefile</span>. Variable files are referenced using a path to them, and
possible arguments are joined to the path with a colon (<span class="opt">:</span>):</p>
<pre class="literal-block">
--variablefile myvariables.py
--variablefile path/variables.py
--variablefile /absolute/path/common.py
--variablefile taking_arguments.py:arg1:arg2
</pre>
<p>Variables in these files are globally available in all test data
files, similarly as <a class="reference internal" href="#setting-variables-in-command-line">individual variables</a> set with the
<span class="opt">--variable</span> option. If both <span class="opt">--variablefile</span> and
<span class="opt">--variable</span> options are used and there are variables with same
names, those that are set individually with
<span class="opt">--variable</span> option take precedence.</p>
</div>
</div>
<div class="section" id="creating-variables-directly">
<h4><a class="toc-backref" href="#id426">Creating variables directly</a></h4>
<div class="section" id="id117">
<h5>Basic syntax</h5>
<p>When variable files are taken into use, they are imported as Python
modules and all their global attributes that do not start with an
underscore (<span class="code">_</span>) are considered to be variables. Because variable
names are case-insensitive, both lower- and upper-case names are
possible, but in general, capital letters are recommended for global
variables and attributes.</p>
<div class="highlight"><pre><span class="n">VARIABLE</span> <span class="o">=</span> <span class="s">&quot;An example string&quot;</span>
<span class="n">ANOTHER_VARIABLE</span> <span class="o">=</span> <span class="s">&quot;This is pretty easy!&quot;</span>
<span class="n">INTEGER</span> <span class="o">=</span> <span class="mi">42</span>
<span class="n">STRINGS</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;one&quot;</span><span class="p">,</span> <span class="s">&quot;two&quot;</span><span class="p">,</span> <span class="s">&quot;kolme&quot;</span><span class="p">,</span> <span class="s">&quot;four&quot;</span><span class="p">]</span>
<span class="n">NUMBERS</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="n">INTEGER</span><span class="p">,</span> <span class="mf">3.14</span><span class="p">]</span>
</pre></div>
<p>In the example above, variables <span class="var">${VARIABLE}</span>,
<span class="var">${ANOTHER_VARIABLE}</span>, and so on, are created. The first two
variables are strings, the third one is an integer and the last two are lists.
All these variables are <a class="reference internal" href="#scalar-variables">scalar variables</a>, even the ones containing
lists as values. To create <a class="reference internal" href="#list-variables">list variables</a>, the variable name must
be prefixed with <span class="code">LIST__</span> (note the two underscores).</p>
<div class="highlight"><pre><span class="n">LIST__STRINGS</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;list&quot;</span><span class="p">,</span> <span class="s">&quot;of&quot;</span><span class="p">,</span> <span class="s">&quot;strings&quot;</span><span class="p">]</span>
<span class="n">LIST__MIXED</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;first value&quot;</span><span class="p">,</span> <span class="o">-</span><span class="mf">1.1</span><span class="p">,</span> <span class="bp">None</span><span class="p">,</span> <span class="bp">True</span><span class="p">]</span>
</pre></div>
<p>The variables in both the examples above could be created also using the
Variable table below.</p>
<table border="1" class="example docutils">
<colgroup>
<col width="28%" />
<col width="30%" />
<col width="15%" />
<col width="13%" />
<col width="13%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Variable</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>${VARIABLE}</td>
<td>An example string</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>${ANOTHER_VARIABLE}</td>
<td>This is pretty easy!</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>${INTEGER}</td>
<td>${42}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>${STRINGS}</td>
<td>one</td>
<td>two</td>
<td>kolme</td>
<td>four</td>
</tr>
<tr><td>${NUMBERS}</td>
<td>${1}</td>
<td>${INTEGER}</td>
<td>${3.14}</td>
<td>&nbsp;</td>
</tr>
<tr><td>&#64;{STRINGS}</td>
<td>list</td>
<td>of</td>
<td>strings</td>
<td>&nbsp;</td>
</tr>
<tr><td>&#64;{MIXED}</td>
<td>first value</td>
<td>${-1.1}</td>
<td>${None}</td>
<td>${True}</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="using-objects-as-values">
<h5>Using objects as values</h5>
<p>Variables in variable files are not limited to having only strings or
other base types as values like variable tables. Instead, their
variables can contain any objects. In the example below, the variable
<span class="var">${MAPPING}</span> contains a Java hashtable with two values (this
example works only when running tests on Jython).</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">java.util</span> <span class="kn">import</span> <span class="n">Hashtable</span>

<span class="n">MAPPING</span> <span class="o">=</span> <span class="n">Hashtable</span><span class="p">()</span>
<span class="n">MAPPING</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s">&quot;one&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="n">MAPPING</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s">&quot;two&quot;</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
</pre></div>
<p>The second example creates <span class="var">${MAPPING}</span> as a Python dictionary
and also has two variables created from a custom object implemented in
the same file.</p>
<div class="highlight"><pre><span class="n">MAPPING</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;one&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s">&#39;two&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">}</span>

<span class="k">class</span> <span class="nc">MyObject</span><span class="p">:</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>

<span class="n">OBJ1</span> <span class="o">=</span> <span class="n">MyObject</span><span class="p">(</span><span class="s">&#39;John&#39;</span><span class="p">)</span>
<span class="n">OBJ2</span> <span class="o">=</span> <span class="n">MyObject</span><span class="p">(</span><span class="s">&#39;Jane&#39;</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="creating-variables-dynamically">
<h5>Creating variables dynamically</h5>
<p>Because variable files are created using a real programming language,
they can have dynamic logic for setting variables.</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span>
<span class="kn">import</span> <span class="nn">random</span>
<span class="kn">import</span> <span class="nn">time</span>

<span class="n">USER</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getlogin</span><span class="p">()</span>                <span class="c"># current login name</span>
<span class="n">RANDOM_INT</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>  <span class="c"># random integer in range [0,10]</span>
<span class="n">CURRENT_TIME</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">asctime</span><span class="p">()</span>       <span class="c"># timestamp like &#39;Thu Apr  6 12:45:21 2006&#39;</span>
<span class="k">if</span> <span class="n">time</span><span class="o">.</span><span class="n">localtime</span><span class="p">()[</span><span class="mi">3</span><span class="p">]</span> <span class="o">&gt;</span> <span class="mi">12</span><span class="p">:</span>
    <span class="n">AFTERNOON</span> <span class="o">=</span> <span class="bp">True</span>
<span class="k">else</span><span class="p">:</span>
    <span class="n">AFTERNOON</span> <span class="o">=</span> <span class="bp">False</span>
</pre></div>
<p>The example above uses standard Python libraries to set different
variables, but you can use your own code to construct the values. The
example below illustrates the concept, but similarly, your code could
read the data from a database, from an external file or even ask it from
the user.</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">math</span>

<span class="k">def</span> <span class="nf">get_area</span><span class="p">(</span><span class="n">diameter</span><span class="p">):</span>
    <span class="n">radius</span> <span class="o">=</span> <span class="n">diameter</span> <span class="o">/</span> <span class="mi">2</span>
    <span class="n">area</span> <span class="o">=</span> <span class="n">math</span><span class="o">.</span><span class="n">pi</span> <span class="o">*</span> <span class="n">radius</span> <span class="o">*</span> <span class="n">radius</span>
    <span class="k">return</span> <span class="n">area</span>

<span class="n">AREA1</span> <span class="o">=</span> <span class="n">get_area</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="n">AREA2</span> <span class="o">=</span> <span class="n">get_area</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="selecting-which-variables-to-include">
<h5>Selecting which variables to include</h5>
<p>When Robot Framework processes variable files, all their attributes
that do not start with an underscore are expected to be
variables. This means that even functions or classes created in the
variable file or imported from elsewhere are considered variables. For
example, the last example would contain the variables <span class="var">${math}</span>
and <span class="var">${get_area}</span> in addition to <span class="var">${AREA1}</span> and
<span class="var">${AREA2}</span>.</p>
<p>Normally the extra variables do not cause problems, but they
could override some other variables and cause hard-to-debug
errors. One possibility to ignore other attributes is prefixing them
with an underscore:</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">math</span> <span class="kn">as</span> <span class="nn">_math</span>

<span class="k">def</span> <span class="nf">_get_area</span><span class="p">(</span><span class="n">diameter</span><span class="p">):</span>
    <span class="n">radius</span> <span class="o">=</span> <span class="n">diameter</span> <span class="o">/</span> <span class="mf">2.0</span>
    <span class="n">area</span> <span class="o">=</span> <span class="n">_math</span><span class="o">.</span><span class="n">pi</span> <span class="o">*</span> <span class="n">radius</span> <span class="o">*</span> <span class="n">radius</span>
    <span class="k">return</span> <span class="n">area</span>

<span class="n">AREA1</span> <span class="o">=</span> <span class="n">_get_area</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="n">AREA2</span> <span class="o">=</span> <span class="n">_get_area</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
</pre></div>
<p>If there is a large number of other attributes, instead of prefixing
them all, it is often easier to use a special attribute
<span class="code">__all__</span> and give it a list of attribute names to be processed
as variables.</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">math</span>

<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s">&#39;AREA1&#39;</span><span class="p">,</span> <span class="s">&#39;AREA2&#39;</span><span class="p">]</span>

<span class="k">def</span> <span class="nf">get_area</span><span class="p">(</span><span class="n">diameter</span><span class="p">):</span>
    <span class="n">radius</span> <span class="o">=</span> <span class="n">diameter</span> <span class="o">/</span> <span class="mf">2.0</span>
    <span class="n">area</span> <span class="o">=</span> <span class="n">math</span><span class="o">.</span><span class="n">pi</span> <span class="o">*</span> <span class="n">radius</span> <span class="o">*</span> <span class="n">radius</span>
    <span class="k">return</span> <span class="n">area</span>

<span class="n">AREA1</span> <span class="o">=</span> <span class="n">get_area</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="n">AREA2</span> <span class="o">=</span> <span class="n">get_area</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
</pre></div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The <span class="code">__all__</span> attribute is also, and originally, used
by Python to decide which attributes to import
when using the syntax <span class="code">from modulename import *</span>.</p>
</div>
</div>
</div>
<div class="section" id="getting-variables-from-a-special-function">
<h4><a class="toc-backref" href="#id427">Getting variables from a special function</a></h4>
<p>An alternative syntax for getting variables is having a special
<span class="code">get_variables</span> function (also camelCase syntax
<span class="code">getVariables</span> is possible) in the variable file. In this case,
Robot Framework calls that function and it returns variables as a
Python dictionary or its subclass or a Java <span class="code">Map</span>, with variable names as keys
and variable values as values. (Note: Prior to Robot Framework 2.5 only
Python dictionaries were supported.) Variables are considered to be scalars,
unless prefixed with <span class="code">LIST__</span>, and values can contain
anything. The example below is identical to the first examples of
<a class="reference internal" href="#creating-variables-directly">creating variables directly</a>.</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">get_variables</span><span class="p">():</span>
    <span class="n">variables</span> <span class="o">=</span> <span class="p">{</span> <span class="s">&quot;VARIABLE &quot;</span><span class="p">:</span> <span class="s">&quot;An example string&quot;</span><span class="p">,</span>
                  <span class="s">&quot;ANOTHER_VARIABLE&quot;</span><span class="p">:</span> <span class="s">&quot;This is pretty easy!&quot;</span><span class="p">,</span>
                  <span class="s">&quot;INTEGER&quot;</span><span class="p">:</span> <span class="mi">42</span><span class="p">,</span>
                  <span class="s">&quot;STRINGS&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s">&quot;one&quot;</span><span class="p">,</span> <span class="s">&quot;two&quot;</span><span class="p">,</span> <span class="s">&quot;kolme&quot;</span><span class="p">,</span> <span class="s">&quot;four&quot;</span><span class="p">],</span>
                  <span class="s">&quot;NUMBERS&quot;</span><span class="p">:</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">42</span><span class="p">,</span> <span class="mf">3.14</span><span class="p">],</span>
                  <span class="s">&quot;LIST__STRINGS&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s">&quot;list&quot;</span><span class="p">,</span> <span class="s">&quot;of&quot;</span><span class="p">,</span> <span class="s">&quot;strings&quot;</span><span class="p">],</span>
                  <span class="s">&quot;LIST__MIXED&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s">&quot;first value&quot;</span><span class="p">,</span> <span class="o">-</span><span class="mf">1.1</span><span class="p">,</span> <span class="bp">None</span><span class="p">,</span> <span class="bp">True</span><span class="p">]</span> <span class="p">}</span>
    <span class="k">return</span> <span class="n">variables</span>
</pre></div>
<p><span class="code">get_variables</span> can also take arguments, which facilitates changing
what variables actually are created. Arguments to the function are set just
as any other arguments for a Python function. When <a class="reference internal" href="#taking-variable-files-into-use">taking variable files
into use</a> in the test data, arguments are specified in cells after the path
to the variable file, and in the command line they are separated from the
path with a colon.</p>
<p>The dummy example below shows how to use arguments with variable files. In a
more realistic example, the argument could be a path to an external text file
or database where to read variables from.</p>
<div class="highlight"><pre><span class="n">variables1</span> <span class="o">=</span> <span class="p">{</span> <span class="s">&#39;scalar&#39;</span><span class="p">:</span> <span class="s">&#39;Scalar variable&#39;</span><span class="p">,</span>
               <span class="s">&#39;LIST__list&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s">&#39;List&#39;</span><span class="p">,</span><span class="s">&#39;variable&#39;</span><span class="p">]</span> <span class="p">}</span>
<span class="n">variables2</span> <span class="o">=</span> <span class="p">{</span> <span class="s">&#39;scalar&#39;</span> <span class="p">:</span> <span class="s">&#39;Some other value&#39;</span><span class="p">,</span>
               <span class="s">&#39;LIST__list&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s">&#39;Some&#39;</span><span class="p">,</span><span class="s">&#39;other&#39;</span><span class="p">,</span><span class="s">&#39;value&#39;</span><span class="p">],</span>
               <span class="s">&#39;extra&#39;</span><span class="p">:</span> <span class="s">&#39;variables1 does not have this at all&#39;</span> <span class="p">}</span>

<span class="k">def</span> <span class="nf">get_variables</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">arg</span> <span class="o">==</span> <span class="s">&#39;one&#39;</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">variables1</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">variables2</span>
</pre></div>
<p>The most notable benefit of using <span class="code">get_variables</span> instead of
defining variables directly as global attributes of the variable file
is the ability to use arguments. On the other hand, the main drawback
is that this approach always requires some actual programming.</p>
</div>
</div>
</div>
<div class="section" id="advanced-features">
<h2><a class="toc-backref" href="#id326">2.8&nbsp;&nbsp;&nbsp;Advanced features</a></h2>
<div class="contents local topic" id="id118">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#handling-keywords-with-same-names" id="id428">2.8.1&nbsp;&nbsp;&nbsp;Handling keywords with same names</a><ul>
<li><a class="reference internal" href="#keyword-scopes" id="id429">Keyword scopes</a></li>
<li><a class="reference internal" href="#specifying-a-keyword-explicitly" id="id430">Specifying a keyword explicitly</a></li>
<li><a class="reference internal" href="#specifying-explicit-priority-between-libraries-and-resources" id="id431">Specifying explicit priority between libraries and resources</a></li>
</ul>
</li>
<li><a class="reference internal" href="#timeouts" id="id432">2.8.2&nbsp;&nbsp;&nbsp;Timeouts</a><ul>
<li><a class="reference internal" href="#test-case-timeout" id="id433">Test case timeout</a></li>
<li><a class="reference internal" href="#user-keyword-timeout" id="id434">User keyword timeout</a></li>
</ul>
</li>
<li><a class="reference internal" href="#for-loops" id="id435">2.8.3&nbsp;&nbsp;&nbsp;For loops</a><ul>
<li><a class="reference internal" href="#normal-for-loop" id="id436">Normal for loop</a></li>
<li><a class="reference internal" href="#using-several-loop-variables" id="id437">Using several loop variables</a></li>
<li><a class="reference internal" href="#for-in-range" id="id438">For in range</a></li>
<li><a class="reference internal" href="#exiting-for-loop" id="id439">Exiting for loop</a></li>
<li><a class="reference internal" href="#repeating-single-keyword" id="id440">Repeating single keyword</a></li>
</ul>
</li>
<li><a class="reference internal" href="#conditional-execution" id="id441">2.8.4&nbsp;&nbsp;&nbsp;Conditional execution</a></li>
<li><a class="reference internal" href="#parallel-execution-of-keywords" id="id442">2.8.5&nbsp;&nbsp;&nbsp;Parallel execution of keywords</a></li>
</ul>
</div>
<div class="section" id="handling-keywords-with-same-names">
<h3><a class="toc-backref" href="#id428">2.8.1&nbsp;&nbsp;&nbsp;Handling keywords with same names</a></h3>
<p>Keywords that are used with Robot Framework are either <a class="reference internal" href="#using-test-libraries">library
keywords</a> or <a class="reference internal" href="#creating-user-keywords">user keywords</a>. The former come from <a class="reference internal" href="#standard-libraries">standard
libraries</a> or <a class="reference internal" href="#external-libraries">external libraries</a>, and the latter are either
created in the same file where they are used or then imported from
<a class="reference internal" href="#resource-files">resource files</a>. When many keywords are in use, it is quite common
that some of them have the same name, and this section describes how to
handle possible conflicts in these situations.</p>
<div class="section" id="keyword-scopes">
<h4><a class="toc-backref" href="#id429">Keyword scopes</a></h4>
<p>When only a keyword name is used and there are several keywords with
that name, Robot Framework attempts to determine which keyword has the
highest priority based on its scope. The keyword's scope is determined
on the basis of how the keyword in question is created:</p>
<ol class="arabic simple">
<li>Created as a user keyword in the same file where it is used. These
keywords have the highest priority and they are always used, even
if there are other keywords with the same name elsewhere.</li>
<li>Created in a resource file and imported either directly or
indirectly from another resource file. This is the second-highest
priority.</li>
<li>Created in an external test library. These keywords are used, if
there are no user keywords with the same name. However, if there is
a keyword with the same name in the standard library, a warning is
displayed.</li>
<li>Created in a standard library. These keywords have the lowest
priority.</li>
</ol>
</div>
<div class="section" id="specifying-a-keyword-explicitly">
<h4><a class="toc-backref" href="#id430">Specifying a keyword explicitly</a></h4>
<p>Scopes alone are not a sufficient solution, because there can be
keywords with the same name in several libraries or resources, and
thus, they provide a mechanism to use only the keyword of the
highest priority. In such cases, it is possible to use <em>the full name
of the keyword</em>, where the keyword name is prefixed with the name of
the resource or library and a dot is a delimiter.</p>
<p>With library keywords, the long format means only using the format
<span class="name">LibraryName.Keyword Name</span>. For example, the keyword <span class="name">Run</span>
from the <a class="reference internal" href="#operatingsystem-library">OperatingSystem library</a> could be used as
<span class="name">OperatingSystem.Run</span>, even if there was another <span class="name">Run</span>
keyword somewhere else. If the library is in a module or package, the
full module or package name must be used (for example,
<span class="name">com.company.Library.Some Keyword</span>). If a custom name is given
to a library using the <a class="reference internal" href="#setting-custom-name-to-test-library">WITH NAME syntax</a>, the specified name must be
used also in the full keyword name.</p>
<p>Resource files are specified in the full keyword name, similarly as
library names. The name of the resource is derived from the basename
of the resource file without the file extension. For example, the
keyword <span class="name">Example</span> in a resource file <span class="path">myresources.html</span> can
be used as <span class="name">myresources.Example</span>. Note that this syntax does not
work, if several resource files have the same basename. In such
cases, either the files or the keywords must be renamed. The full name
of the keyword is case-, space- and underscore-insensitive, similarly
as normal keyword names.</p>
</div>
<div class="section" id="specifying-explicit-priority-between-libraries-and-resources">
<h4><a class="toc-backref" href="#id431">Specifying explicit priority between libraries and resources</a></h4>
<p>If there are multiple conflicts between keywords, specifying all the keywords
in the long format can be quite a lot work. Using the long format also makes it
impossible to create dynamic test cases or user keywords that work differently
depending on which libraries or resources are available. A solution to both of
these problems is specifying the keyword priorities explicitly using the keyword
<span class="name">Set Library Search Order</span> from the <a class="reference internal" href="#builtin-library">BuiltIn library</a>.</p>
<blockquote>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Although the keyword has the word <cite>library</cite> in its name, it works
also with resource files starting from Robot Framework 2.6.2.
As discussed above, keywords in resources always have higher
priority than keywords in libraries, though.</p>
</div>
</blockquote>
<p>The <span class="name">Set Library Search Order</span> accepts an ordered list or libraries and
resources as arguments. When a keyword name in the test data matches multiple
keywords, the first library or resource containing the keyword is selected and
that keyword implementation used. If the keyword is not found from any of the
specified libraries or resources, execution fails for conflict the same way as
when the search order is not set.</p>
<p>For more information and examples, see the documentation of the keyword.</p>
</div>
</div>
<div class="section" id="timeouts">
<h3><a class="toc-backref" href="#id432">2.8.2&nbsp;&nbsp;&nbsp;Timeouts</a></h3>
<p>Keywords may be problematic in situations where they take
exceptionally long to execute or just hang endlessly. Robot Framework
allows you to set timeouts both for <a class="reference internal" href="#creating-test-cases">test cases</a> and <a class="reference internal" href="#creating-user-keywords">user
keywords</a>, and if a test or keyword is not finished within the
specified time, the keyword that is currently being executed is
forcefully stopped. Stopping keywords in this manner may leave the
library or system under test to an unstable state, and timeouts are
recommended only when there is no safer option available. In general,
libraries should be implemented so that keywords cannot hang or that
they have their own timeout mechanism, if necessary.</p>
<div class="section" id="test-case-timeout">
<h4><a class="toc-backref" href="#id433">Test case timeout</a></h4>
<p>The test case timeout can be set either by using the <span class="opt">Test
Timeout</span> setting in the Setting table or the <span class="opt">[Timeout]</span>
setting in the Test Case table. <span class="opt">Test Timeout</span> in the Setting
table defines a default test timeout value for all the test cases in
the test suite, whereas <span class="opt">[Timeout]</span> in the Test Case table
applies a timeout to an individual test case and overrides the
possible default value.</p>
<p>Using an empty <span class="opt">[Timeout]</span> means that the test has no
timeout even when <span class="opt">Test Timeout</span> is used. Starting from Robot Framework
2.5.6, it is also possible to use value <span class="misc">NONE</span> for this purpose.</p>
<p>Regardless of where the test timeout is defined, the first cell after
the setting name contains the duration of the timeout. The duration
must be given in Robot Framework's <a class="reference internal" href="#time-format">time format</a>, that is,
either directly in seconds or in a format like <span class="code">1 minute
30 seconds</span>. It must be noted that there is always some overhead by the
framework, and timeouts shorter than one second are thus not
recommended.</p>
<p>The default error message displayed when a test timeout occurs is
<span class="msg">Test timeout &lt;time&gt; exceeded</span>. It is also possible to use custom
error messages, and these messages are written into the cells
after the timeout duration. The message can be split into multiple
cells, similarly as documentations. Both the timeout value and the
error message may contain variables.</p>
<p>If there is a timeout, the keyword running is stopped at the
expiration of the timeout and the test case fails. However, keywords
executed as <a class="reference internal" href="#test-setup-and-teardown">test teardown</a> are not interrupted if a test timeout
occurs, because they are normally engaged in important clean-up
activities. If necessary, it is possible to interrupt also these
keywords with <a class="reference internal" href="#user-keyword-timeout">user keyword timeouts</a>.</p>
<table border="1" class="example docutils">
<caption>Test timeout examples</caption>
<colgroup>
<col width="34%" />
<col width="26%" />
<col width="20%" />
<col width="20%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Test Timeout</td>
<td>2 minutes</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="13%" />
<col width="13%" />
<col width="35%" />
<col width="23%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Default Timeout</td>
<td>[Documentation]</td>
<td>Timeout from the Setting table is used</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Some Keyword</td>
<td>argument</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Override</td>
<td>[Documentation]</td>
<td>Override default, use 10 seconds timeout</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Timeout]</td>
<td>10</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Some Keyword</td>
<td>argument</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Custom Message</td>
<td>[Documentation]</td>
<td>Override default and use custom message</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Timeout]</td>
<td>1min 10s</td>
<td>This is my custom error.</td>
<td>It continues here.</td>
</tr>
<tr><td></td>
<td>Some Keyword</td>
<td>argument</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Variables</td>
<td>[Documentation]</td>
<td>It is possible to use variables too</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Timeout]</td>
<td>${TIMEOUT}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Some Keyword</td>
<td>argument</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>No Timeout</td>
<td>[Documentation]</td>
<td>Empty timeout means no timeout even when</td>
<td>Test Timeout has been used</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Timeout]</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Some Keyword</td>
<td>argument</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>No Timeout 2</td>
<td>[Documentation]</td>
<td>Empty timeout using NONE, works with</td>
<td>2.5.6</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Timeout]</td>
<td>NONE</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Some Keyword</td>
<td>argument</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="user-keyword-timeout">
<h4><a class="toc-backref" href="#id434">User keyword timeout</a></h4>
<p>A timeout can be set for a user keyword using the <span class="opt">[Timeout]</span>
setting in the Keyword table. The syntax for setting it, including how
timeout values and possible custom messages are given, is
identical to the syntax used with <a class="reference internal" href="#test-case-timeout">test case timeouts</a>. If no custom
message is provided, the default error message <span class="msg">Keyword timeout
&lt;time&gt; exceeded</span> is used if a timeout occurs.</p>
<table border="1" class="example docutils">
<caption>User keyword timeout examples</caption>
<colgroup>
<col width="17%" />
<col width="17%" />
<col width="25%" />
<col width="42%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Keyword</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Timed Keyword</td>
<td>[Documentation]</td>
<td>Set only the timeout value</td>
<td>and not the custom message.</td>
</tr>
<tr><td></td>
<td>[Timeout]</td>
<td>1 minute 42 seconds</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Do Something</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Do Something Else</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Timed-out Wrapper</td>
<td>[Arguments]</td>
<td>&#64;{args}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>[Documentation]</td>
<td>This keyword is a wrapper</td>
<td>that adds a timeout to another keyword.</td>
</tr>
<tr><td></td>
<td>[Timeout]</td>
<td>2 minutes</td>
<td>Original Keyword didn't finish in 2 minutes</td>
</tr>
<tr><td></td>
<td>Original Keyword</td>
<td>&#64;{args}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>A user keyword timeout is applicable during the execution of that user
keyword. If the total time of the whole keyword is longer than the
timeout value, the currently executed keyword is stopped. User keyword
timeouts are applicable also during a test case teardown, whereas test
timeouts are not.</p>
<p>If both the test case and some of its keywords (or several nested
keywords) have a timeout, the active timeout is the one with the least
time left.</p>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">Using timeouts might slow down test execution when using Python 2.5
elsewhere than on Windows. Prior to Robot Framework 2.7 timeouts
slowed down execution with all Python versions on all platforms.</p>
</div>
</div>
</div>
<div class="section" id="for-loops">
<h3><a class="toc-backref" href="#id435">2.8.3&nbsp;&nbsp;&nbsp;For loops</a></h3>
<p>Repeating same actions several times is quite a common need in test
automation. With Robot Framework, test libraries can have any kind of
loop constructs, and most of the time loops should be implemented in
them. Robot Framework also has its own For loop syntax, which is
useful, for example, when there is a need to repeat keywords from
different libraries.</p>
<p>For loops can be used with both test cases and user keywords. Except for
really simple cases, user keywords are better, because they hide the
complexity introduced by for loops. The basic for loop syntax,
<span class="code">FOR item IN sequence</span>, is derived from Python, but similar
syntax is possible also in shell scripts or Perl.</p>
<div class="section" id="normal-for-loop">
<h4><a class="toc-backref" href="#id436">Normal for loop</a></h4>
<p>In a normal For loop, one variable is assigned from a list of values,
one value per iteration. The syntax starts with <span class="name">:FOR</span>, where
colon is required to separate the syntax from normal keywords. The
next cell contains the loop variable, the subsequent cell must have
<span class="name">IN</span>, and the final cells contain values over which to iterate.</p>
<p>The keywords used in the For loop are on the next rows and they must
be indented one cell to the right. The For loop ends when the indentation
returns back to normal or the table ends. Having nested For loops
directly is not supported, but it is possible to use a user keyword
inside a For loop and have another For loop there.</p>
<table border="1" class="example docutils">
<caption>Simple for loops</caption>
<colgroup>
<col width="17%" />
<col width="13%" />
<col width="19%" />
<col width="17%" />
<col width="16%" />
<col width="17%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Arguments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example 1</td>
<td>:FOR</td>
<td>${animal}</td>
<td>IN</td>
<td>cat</td>
<td>dog</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Log</td>
<td>${animal}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Log</td>
<td>2nd keyword</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Log</td>
<td>Outside loop</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Example 2</td>
<td>:FOR</td>
<td>${var}</td>
<td>IN</td>
<td>one</td>
<td>two</td>
</tr>
<tr><td></td>
<td>...</td>
<td>three</td>
<td>four</td>
<td>five</td>
<td>six</td>
</tr>
<tr><td></td>
<td>...</td>
<td>seven</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Log</td>
<td>${var}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>The For loop in <span class="name">Example 1</span> above is executed twice, so that first
the loop variable <span class="var">${animal}</span> has the value <span class="code">cat</span> and then
<span class="code">dog</span>. The loop consists of two <span class="name">Log</span> keywords. In the
second example, loop values are <a class="reference internal" href="#dividing-test-data-to-several-rows">split into several rows</a> and the
loop is run altogether seven times.</p>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p>If you use for loops in the <a class="reference internal" href="#plain-text-format">plain text format</a>, remember to
<a class="reference internal" href="#escaping">escape</a> the indented cell using a backslash:</p>
<pre class="last literal-block">
*** Test Case ***
Example 1
    :FOR    ${animal}    IN    cat    dog
    \    Log    ${animal}
    \    Log    2nd keyword
    Log    Outside loop
</pre>
</div>
<p>For loops are most useful and also clearest when they are used with
<a class="reference internal" href="#list-variables">list variables</a>. This is illustrated by the example below, where
<span class="var">&#64;{ELEMENTS}</span> contains an arbitrarily long list of element names
and keyword <span class="name">Start Element</span> is used with all of them.</p>
<table border="1" class="example docutils">
<caption>For loop with a list variable</caption>
<colgroup>
<col width="17%" />
<col width="13%" />
<col width="20%" />
<col width="16%" />
<col width="17%" />
<col width="17%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Arguments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>:FOR</td>
<td>${element}</td>
<td>IN</td>
<td>&#64;{ELEMENTS}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Start Element</td>
<td>${element}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="using-several-loop-variables">
<h4><a class="toc-backref" href="#id437">Using several loop variables</a></h4>
<p>It is also possible to use several loop variables. The syntax is the
same as with the normal For loop, but all loop variables are listed in
the cells between <span class="name">:FOR</span> and <span class="name">IN</span>. There can be any number of loop
variables, but the number of values must be evenly dividable by the number of
variables.</p>
<p>This syntax naturally works both with and without list variables. In
the former case, it is often possible to organize loop values below
loop variables, as in the first part of the example below:</p>
<table border="1" class="example docutils">
<caption>Using multiple loop variables</caption>
<colgroup>
<col width="18%" />
<col width="13%" />
<col width="18%" />
<col width="16%" />
<col width="16%" />
<col width="19%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Arguments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>:FOR</td>
<td>${index}</td>
<td>${english}</td>
<td>${finnish}</td>
<td>IN</td>
</tr>
<tr><td></td>
<td>...</td>
<td>1</td>
<td>cat</td>
<td>kissa</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>...</td>
<td>2</td>
<td>dog</td>
<td>koira</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>...</td>
<td>3</td>
<td>horse</td>
<td>hevonen</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Do X</td>
<td>${english}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Y Should Be</td>
<td>${finnish}</td>
<td>${index}</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>:FOR</td>
<td>${name}</td>
<td>${id}</td>
<td>IN</td>
<td>&#64;{EMPLOYERS}</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Create</td>
<td>${name}</td>
<td>${id}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="for-in-range">
<h4><a class="toc-backref" href="#id438">For in range</a></h4>
<p>Earlier For loops always iterated over a sequence, and this is also the most
common use case. Sometimes it is still convenient to have a For loop
that is executed a certain number of times, and Robot Framework has a
special <span class="code">FOR index IN RANGE limit</span> syntax for this purpose. This
syntax is derived from the similar Python idiom.</p>
<p>Similarly as other For loops, the For in range loop starts with
<span class="name">:FOR</span> and the loop variable is in the next cell. In this format
there can be only one loop variable and it contains the current loop
index. The next cell must contain <span class="name">IN RANGE</span> and the subsequent
cells loop limits.</p>
<p>In the simplest case, only the upper limit of the loop is
specified. In this case, loop indexes start from zero and increase by one
until, but excluding, the limit. It is also possible to give both the
start and end limits. Then indexes start from the start limit, but
increase similarly as in the simple case. Finally, it is possible to give
also the step value that specifies the increment to use. If the step
is negative, it is used as decrement.</p>
<p>Starting from Robot Framework 2.5.5, it is possible to use simple arithmetics
such as addition and subtraction with the range limits. This is especially
useful when the limits are specified with variables.</p>
<table border="1" class="example docutils">
<caption>For in range examples</caption>
<colgroup>
<col width="21%" />
<col width="20%" />
<col width="14%" />
<col width="13%" />
<col width="11%" />
<col width="11%" />
<col width="11%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Arg</th>
<th class="head">Arg</th>
<th class="head">Arg</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Only upper limit</td>
<td>[Documentation]</td>
<td>Loops over</td>
<td>values</td>
<td>from 0</td>
<td>to 9</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>:FOR</td>
<td>${index}</td>
<td>IN RANGE</td>
<td>10</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Log</td>
<td>${index}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Start and end</td>
<td>[Documentation]</td>
<td>Loops over</td>
<td>values</td>
<td>from 1</td>
<td>to 10</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>:FOR</td>
<td>${index}</td>
<td>IN RANGE</td>
<td>1</td>
<td>11</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Log</td>
<td>${index}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Also step given</td>
<td>[Documentation]</td>
<td>Loops over</td>
<td>values</td>
<td>5, 15,</td>
<td>and 25</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>:FOR</td>
<td>${index}</td>
<td>IN RANGE</td>
<td>5</td>
<td>26</td>
<td>10</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Log</td>
<td>${index}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Negative step</td>
<td>[Documentation]</td>
<td>Loops over</td>
<td>values</td>
<td>13, 3,</td>
<td>and -7</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>:FOR</td>
<td>${index}</td>
<td>IN RANGE</td>
<td>13</td>
<td>-13</td>
<td>-10</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Log</td>
<td>${index}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Arithmetics</td>
<td>[Documentation]</td>
<td>Arithmetics</td>
<td>with</td>
<td>variable</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>:FOR</td>
<td>${index}</td>
<td>IN RANGE</td>
<td>${var}+1</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Log</td>
<td>${index}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="exiting-for-loop">
<h4><a class="toc-backref" href="#id439">Exiting for loop</a></h4>
<p>Normally for loop is executed until all the elements of the loop have been
looped through or an error occurs and the test case or keyword fails. However
sometimes execution of a for loop needs to be stopped before all elements of
the loop have been gone through. <a class="reference internal" href="#builtin-library">BuiltIn keyword</a> <span class="name">Exit For Loop</span> can be
used to exit the enclosing for loop.</p>
<p><span class="name">Exit For Loop</span> keyword can be used directly in a for loop or in a keyword
that the for loop uses. In both cases the test execution continues after the
for loop. If executed outside of a for loop, the test fails.</p>
<table border="1" class="example docutils">
<caption>Exit for loop example</caption>
<colgroup>
<col width="19%" />
<col width="12%" />
<col width="21%" />
<col width="26%" />
<col width="22%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Exit Example</td>
<td>:FOR</td>
<td>${var}</td>
<td>IN</td>
<td>&#64;{SOME LIST}</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Run Keyword If</td>
<td>'${var}' == 'EXIT'</td>
<td>Exit For Loop</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>Do Something</td>
<td>${var}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>Exiting a for loop can also be initiated from a keyword in a test library by
raising an exception with <span class="code">ROBOT_EXIT_FOR_LOOP</span> attribute. Please see
<a class="reference internal" href="#stopping-test-execution">Stopping test execution</a> for examples how to do this in Python and Java
libraries.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Exit for loop functionality is new in Robot Framework 2.5.2.</p>
</div>
</div>
<div class="section" id="repeating-single-keyword">
<h4><a class="toc-backref" href="#id440">Repeating single keyword</a></h4>
<p>For loops can be excessive in situations where there is only a need to
repeat a single keyword. In these cases it is often easier to use
<a class="reference internal" href="#builtin-library">BuiltIn keyword</a> <span class="name">Repeat Keyword</span>.  This keyword takes a
keyword and how many times to repeat it as arguments. The times to
repeat the keyword can have an optional postfix <cite>times</cite> or <cite>x</cite> to make
the syntax easier to read.</p>
<table border="1" class="example docutils">
<caption>Repeat Keyword examples</caption>
<colgroup>
<col width="17%" />
<col width="22%" />
<col width="18%" />
<col width="18%" />
<col width="12%" />
<col width="12%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>Repeat Keyword</td>
<td>5</td>
<td>Some Keyword</td>
<td>arg1</td>
<td>arg2</td>
</tr>
<tr><td></td>
<td>Repeat Keyword</td>
<td>42 times</td>
<td>My Keyword</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Repeat Keyword</td>
<td>${var}</td>
<td>Another KW</td>
<td>argument</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>Robot Framework also had a special syntax for repeating a single
keyword. This syntax was deprecated in the 2.0.4 version in favor of
<span class="name">Repeat Keyword</span> and it was removed in the 2.5 version.</p>
</div>
</div>
<div class="section" id="conditional-execution">
<h3><a class="toc-backref" href="#id441">2.8.4&nbsp;&nbsp;&nbsp;Conditional execution</a></h3>
<p>In general, it is not recommended to have conditional logic in test
cases, or even in user keywords, because it can make them hard to
understand and maintain. Instead, this kind of logic should be in test
libraries, where it can be implemented using natural programming
language constructs. However, some conditional logic can be useful at
times, and even though Robot Framework does not have an actual if/else
construct, there are several ways to get the same effect.</p>
<ul class="simple">
<li>The name of the keyword used as a setup or a teardown of both <a class="reference internal" href="#test-setup-and-teardown">test
cases</a> and <a class="reference internal" href="#suite-setup-and-teardown">test suites</a> can be specified using a
variable. This facilitates changing them, for example, from
the command line.</li>
<li>The <a class="reference internal" href="#builtin-library">BuiltIn keyword</a> <span class="name">Run Keyword</span> takes a keyword to actually
execute as an argument, and it can thus be a variable. The value of
the variable can, for example, be got dynamically from an earlier
keyword or given from the command line.</li>
<li>The <a class="reference internal" href="#builtin-library">BuiltIn keywords</a> <span class="name">Run Keyword If</span> and <span class="name">Run Keyword
Unless</span> execute a named keyword only if a certain expression is
true or false, respectively. They are ideally suited to creating
simple if/else constructs. For an example, see the documentation of
the former.</li>
<li>Another <a class="reference internal" href="#builtin-library">BuiltIn keyword</a>, <span class="name">Set Variable If</span>, can be used to set
variables dynamically based on a given expression.</li>
<li>There are several <a class="reference internal" href="#builtin-library">BuiltIn keywords</a> that allow executing a named
keyword only if a test case or test suite has failed or passed.</li>
</ul>
</div>
<div class="section" id="parallel-execution-of-keywords">
<h3><a class="toc-backref" href="#id442">2.8.5&nbsp;&nbsp;&nbsp;Parallel execution of keywords</a></h3>
<p>Prior to the 2.5 version Robot Framework a had special syntax for executing
keywords in parallel. This functionality was removed because it was rarely
used and it never worked fully.</p>
<p>When parallel execution is needed, it must be implemented in test library
level so that the library executes the code on background. Typically this
means that the library needs a keyword like <span class="name">Start Something</span> that
starts the execution and returns immediately, and another keyword like
<span class="name">Get Results From Something</span> that waits until the result is available
and returns it. See <a class="reference internal" href="#operatingsystem-library">OperatingSystem library</a> keywords <span class="name">Start Process</span>
and <span class="name">Read Process Output</span> for an example.</p>
</div>
</div>
</div>
<div class="section" id="executing-test-cases">
<h1><a class="toc-backref" href="#id270">3&nbsp;&nbsp;&nbsp;Executing test cases</a></h1>
<div class="contents local topic" id="id123">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#basic-usage" id="id443">3.1&nbsp;&nbsp;&nbsp;Basic usage</a></li>
<li><a class="reference internal" href="#test-execution" id="id444">3.2&nbsp;&nbsp;&nbsp;Test execution</a></li>
<li><a class="reference internal" href="#post-processing-outputs" id="id445">3.3&nbsp;&nbsp;&nbsp;Post-processing outputs</a></li>
<li><a class="reference internal" href="#configuring-execution" id="id446">3.4&nbsp;&nbsp;&nbsp;Configuring execution</a></li>
<li><a class="reference internal" href="#created-outputs" id="id447">3.5&nbsp;&nbsp;&nbsp;Created outputs</a></li>
</ul>
</div>
<div class="section" id="basic-usage">
<h2><a class="toc-backref" href="#id443">3.1&nbsp;&nbsp;&nbsp;Basic usage</a></h2>
<p>Robot Framework test cases are executed from the command line, and the
end result is, by default, an output file in XML format and an HTML
report and log. After the execution, <a class="reference internal" href="#created-outputs">output files</a> can be combined and
otherwise <a class="reference internal" href="#post-processing-outputs">post-processed</a> with the <span class="prog">rebot</span> tool.</p>
<div class="contents local topic" id="id126">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#starting-test-execution" id="id448">3.1.1&nbsp;&nbsp;&nbsp;Starting test execution</a><ul>
<li><a class="reference internal" href="#synopsis" id="id449">Synopsis</a></li>
<li><a class="reference internal" href="#different-runner-scripts" id="id450">Different runner scripts</a></li>
<li><a class="reference internal" href="#specifying-test-data-to-be-executed" id="id451">Specifying test data to be executed</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-command-line-options" id="id452">3.1.2&nbsp;&nbsp;&nbsp;Using command line options</a><ul>
<li><a class="reference internal" href="#using-options" id="id453">Using options</a></li>
<li><a class="reference internal" href="#short-and-long-options" id="id454">Short and long options</a></li>
<li><a class="reference internal" href="#setting-option-values" id="id455">Setting option values</a></li>
<li><a class="reference internal" href="#option-value-as-simple-pattern" id="id456">Option value as simple pattern</a></li>
</ul>
</li>
<li><a class="reference internal" href="#test-results" id="id457">3.1.3&nbsp;&nbsp;&nbsp;Test results</a><ul>
<li><a class="reference internal" href="#command-line-output" id="id458">Command line output</a></li>
<li><a class="reference internal" href="#generated-output-files" id="id459">Generated output files</a></li>
<li><a class="reference internal" href="#return-codes" id="id460">Return codes</a></li>
<li><a class="reference internal" href="#errors-and-warnings-during-execution" id="id461">Errors and warnings during execution</a></li>
</ul>
</li>
<li><a class="reference internal" href="#escaping-complicated-characters" id="id462">3.1.4&nbsp;&nbsp;&nbsp;Escaping complicated characters</a></li>
<li><a class="reference internal" href="#argument-files" id="id463">3.1.5&nbsp;&nbsp;&nbsp;Argument files</a></li>
<li><a class="reference internal" href="#getting-help-and-version-information" id="id464">3.1.6&nbsp;&nbsp;&nbsp;Getting help and version information</a></li>
<li><a class="reference internal" href="#creating-start-up-scripts" id="id465">3.1.7&nbsp;&nbsp;&nbsp;Creating start-up scripts</a><ul>
<li><a class="reference internal" href="#modifying-java-startup-parameters" id="id466">Modifying Java startup parameters</a></li>
</ul>
</li>
<li><a class="reference internal" href="#debugging-problems" id="id467">3.1.8&nbsp;&nbsp;&nbsp;Debugging problems</a></li>
</ul>
</div>
<div class="section" id="starting-test-execution">
<h3><a class="toc-backref" href="#id448">3.1.1&nbsp;&nbsp;&nbsp;Starting test execution</a></h3>
<div class="section" id="synopsis">
<h4><a class="toc-backref" href="#id449">Synopsis</a></h4>
<pre class="literal-block">
pybot [options] datasources
jybot [options] datasources
interpreter /path/to/robot/runner.py [options] datasources
java -jar robotframework-&lt;version&gt;.jar [options] datasources
</pre>
</div>
<div class="section" id="different-runner-scripts">
<h4><a class="toc-backref" href="#id450">Different runner scripts</a></h4>
<p>Test execution is normally started with the <span class="prog">pybot</span> or
<span class="prog">jybot</span> commands. These commands are otherwise identical, but
the former executes tests using the Python interpreter and the latter uses
Jython. Which one to use depends on the needed test libraries. Some
libraries use modules or syntax available only on Python, others use
Java-based tools that require Jython, and some work on both. If you
can use either <span class="prog">pybot</span> or <span class="prog">jybot</span>, the former is
recommended, as Python is somewhat faster than Jython.</p>
<p>Starting from Robot Framework 2.5.2, it is also possible to get Robot Framework
as a single jar file.  In this case, Jython is bundled inside the jar, and the
above discussion about Jython applies. Normal arguments to
Robot Framework are given after the jar file name.</p>
<p>Another possibility for starting the test execution is running the
<span class="prog">runner.py</span> script under the <a class="reference internal" href="#where-files-are-installed">installed</a> <span class="code">robot</span> module
directly. This method allows selecting the interpreter and setting
command line options to it freely. The most common use case is
altering the options controlling <a class="reference internal" href="#modifying-java-startup-parameters">JVM maximum memory consumption</a>.</p>
<p>Regardless of the runner script, the path (or paths) to the test data to be
executed is given as an argument. Additionally, different command line
options can be used to alter the test execution or generated
outputs in some way.</p>
</div>
<div class="section" id="specifying-test-data-to-be-executed">
<h4><a class="toc-backref" href="#id451">Specifying test data to be executed</a></h4>
<p>Robot Framework test cases are created in <a class="reference internal" href="#test-case-files">files</a> and <a class="reference internal" href="#test-suite-directories">directories</a>,
and they are executed by giving the path to the file or directory in
question to the selected runner script. The path can be absolute or,
more commonly, relative to the directory where tests are executed
from. The given file or directory creates the top-level test suite,
which gets its name, unless overridden with the <span class="opt">--name</span> <a class="reference internal" href="#setting-the-name">option</a>,
from the <a class="reference internal" href="#test-suite-name-and-documentation">file or directory name</a>. Different execution possibilities
are illustrated in the examples below. Note that in these examples, as
well as in other examples in this section, only the <span class="prog">pybot</span>
command is used, but <span class="prog">jybot</span> or a custom runner script
could be used similarly.</p>
<pre class="literal-block">
pybot test_cases.html
pybot path/to/my_tests/
pybot c:\robot\tests.txt
</pre>
<p>It is also possible to give paths to several test case files or
directories at once, separated with spaces. In this case, Robot
Framework creates the top-level test suite automatically, and
the specified files and directories become its child test suites. The name
of the created test suite is got from child suite names by
catenating them together with an ampersand (&amp;) and spaces. For example,
the name of the top-level suite in the first example below is
<span class="name">My Tests &amp; Your Tests</span>. These automatically created names are
often quite long and complicated. In most cases, it is thus better to
use the <span class="opt">--name</span> option for overriding it, as in the second
example below:</p>
<pre class="literal-block">
pybot my_tests.html your_tests.html
pybot --name Example path/to/tests/pattern_*.html
</pre>
</div>
</div>
<div class="section" id="using-command-line-options">
<h3><a class="toc-backref" href="#id452">3.1.2&nbsp;&nbsp;&nbsp;Using command line options</a></h3>
<p>Robot Framework provides a number of command line options that can be
used to control how test cases are executed and what outputs are
generated. This section explains the option syntax, and what
options actually exist. How they can be used is discussed elsewhere
in this chapter.</p>
<div class="section" id="using-options">
<h4><a class="toc-backref" href="#id453">Using options</a></h4>
<p>When options are used, they must always be given between the runner
script and the data sources. For example:</p>
<pre class="literal-block">
pybot -L debug my_tests.txt
jybot --include smoke --variable HOST:10.0.0.42 path/to/tests/
</pre>
</div>
<div class="section" id="short-and-long-options">
<h4><a class="toc-backref" href="#id454">Short and long options</a></h4>
<p>Options always have a long name, such as <span class="opt">--name</span>, and the
most frequently needed options also have a short name, such as
<span class="opt">-N</span>. In addition to that, long options can be shortened as
long as they are unique. For example, <span class="cli">--logle DEBUG</span> works,
while <span class="cli">--lo log.html</span> does not, because the former matches only
<span class="opt">--loglevel</span>, but the latter matches several options. Short
and shortened options are practical when executing test cases
manually, but long options are recommended in <a class="reference internal" href="#creating-start-up-scripts">start-up scripts</a>,
because they are easier to understand.</p>
<p>The long option format is case-insensitive, which facilitates writing option
names in an easy-to-read format. For example, <span class="opt">--SuiteStatLevel</span>
is equivalent to, but easier to read than <span class="opt">--suitestatlevel</span>.</p>
</div>
<div class="section" id="setting-option-values">
<h4><a class="toc-backref" href="#id455">Setting option values</a></h4>
<p>Most of the options require a value, which is given after the option
name. Both short and long options accept the value separated
from the option name with a space, as in <span class="cli">--include tag</span>
or <span class="cli">-i tag</span>. With long options, the separator can also be the
equals sign, for example <span class="cli">--include=tag</span>, and with short options the
separator can be omitted, as in <span class="cli">-itag</span>.</p>
<p>Some options can be specified several times. For example,
<span class="cli">--variable VAR1:value --variable VAR2:another</span> sets two
variables. If the options that take only one value are used several
times, the value given last is effective.</p>
</div>
<div class="section" id="option-value-as-simple-pattern">
<h4><a class="toc-backref" href="#id456">Option value as simple pattern</a></h4>
<p>Many of the options take arguments as <em>simple patterns</em>. This means
that <span class="code">*</span> and <span class="code">?</span> can be used as special characters, so
that the former matches any string (even an empty string) and the
latter matches any single character. For example, <span class="cli">--include
prefix-*</span> matches all tags starting with <span class="code">prefix-</span>, and
<span class="cli">--include a???</span> matches any tag that is four characters long and
starts with a character <span class="code">a</span>.</p>
</div>
</div>
<div class="section" id="test-results">
<h3><a class="toc-backref" href="#id457">3.1.3&nbsp;&nbsp;&nbsp;Test results</a></h3>
<div class="section" id="command-line-output">
<h4><a class="toc-backref" href="#id458">Command line output</a></h4>
<p>The most visible output from test execution is the output displayed in
the command line. All executed test suites and test cases, as well as
their statuses, are shown there in real time. The example below shows the
output from executing a simple test suite with only two test cases:</p>
<pre class="literal-block">
==============================================================================
Example test suite
==============================================================================
First test :: Possible test documentation                             | PASS |
------------------------------------------------------------------------------
Second test                                                           | FAIL |
Error message is displayed here
==============================================================================
Example test suite                                                    | FAIL |
2 critical tests, 1 passed, 1 failed
2 tests total, 1 passed, 1 failed
==============================================================================
Output:  /path/to/output.xml
Report:  /path/to/report.html
Log:     /path/to/log.html
</pre>
</div>
<div class="section" id="generated-output-files">
<h4><a class="toc-backref" href="#id459">Generated output files</a></h4>
<p>The command line output is very limited, and separate output files are
normally needed for investigating the test results. As the example
above shows, three output files are generated by default. The first
one is in XML format and contains all the information about test
execution. The second is a higher-level report and the third is a more
detailed log file. These files and other possible output files are
discussed in more detail in the section <a class="reference internal" href="#different-output-files">Different output files</a>.</p>
</div>
<div class="section" id="return-codes">
<h4><a class="toc-backref" href="#id460">Return codes</a></h4>
<p>Runner scripts communicate the overall test execution status to the
system running them using return codes. When the execution starts
successfully and no <a class="reference internal" href="#setting-criticality">critical test</a> fail, the return code is zero.
All possible return codes are explained in the table below.</p>
<table border="1" class="tabular docutils">
<caption>Possible return codes</caption>
<colgroup>
<col width="16%" />
<col width="84%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">RC</th>
<th class="head">Explanation</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>0</td>
<td>All critical tests passed.</td>
</tr>
<tr><td>1-249</td>
<td>Returned number of critical tests failed.</td>
</tr>
<tr><td>250</td>
<td>250 or more critical failures.</td>
</tr>
<tr><td>251</td>
<td>Help or version information printed.</td>
</tr>
<tr><td>252</td>
<td>Invalid test data or command line options.</td>
</tr>
<tr><td>253</td>
<td>Test execution stopped by user.</td>
</tr>
<tr><td>255</td>
<td>Unexpected internal error.</td>
</tr>
</tbody>
</table>
<p>Return codes should always be easily available after the execution,
which makes it easy to automatically determine the overall execution
status. For example, in bash shell the return code is in special
variable <span class="code">$?</span>, and in Windows it is in <span class="code">%ERRORLEVEL%</span>
variable. If you use some external tool for running tests, consult its
documentation for how to get the return code.</p>
<p>Starting from Robot Framework 2.5.7, the return code can be set to 0 even if
there are critical failures using the <span class="opt">--NoStatusRC</span> command line option.
This might be useful, for example, in continuous integration servers where
post-processing of results is needed before the overall status of test
execution can be determined.</p>
</div>
<div class="section" id="errors-and-warnings-during-execution">
<h4><a class="toc-backref" href="#id461">Errors and warnings during execution</a></h4>
<p>During the test execution there can be unexpected problems like
failing to import a library or a resource file or a keyword being
<a class="reference internal" href="#deprecating-keywords">deprecated</a>. Depending on the severity such problems are categorized
as errors or warnings and they are written into the console (using the
standard error stream), shown on a separate <em>Test Execution Errors</em>
section in log files, and also written into Robot Framework's own
<a class="reference internal" href="#system-log">system log</a>. Normally these errors are generated by Robot Framework
core, but libraries can use <a class="reference internal" href="#logging-information">log level WARN</a> to write warnings.
Example below illustrates how errors and warnings look like in the log
file.</p>
<table class="messages">
  <tr>
    <td class="time">20090322&nbsp;19:58:42.528</td>
    <td class="error level">ERROR</td>
    <td class="msg">Error in file '/home/robot/tests.html' in table 'Setting' in element on row 2: Resource file 'resource.html' does not exist</td>
  </tr>
  <tr>
    <td class="time">20090322&nbsp;19:58:43.931</td>
    <td class="warn level">WARN</td>
    <td class="msg">Keyword 'SomeLibrary.Example Keyword' is deprecated. Use keyword `Other Keyword` instead.</td>
  </tr>
</table></div>
</div>
<div class="section" id="escaping-complicated-characters">
<h3><a class="toc-backref" href="#id462">3.1.4&nbsp;&nbsp;&nbsp;Escaping complicated characters</a></h3>
<p>Because spaces are used for separating options from each other, it is
problematic to use them in option values.  Some options, such as
<span class="opt">--name</span>, automatically convert underscores to spaces, but
with others spaces must be escaped. Additionally, many special
characters are complicated to use on the command line.
Because escaping complicated characters with a backslash or quoting
the values does not always work too well, Robot Framework has its own
generic escaping mechanism. Another possibility is using <a class="reference internal" href="#argument-files">argument
files</a> where options can be specified in the plain text format. Both of
these mechanisms work when executing tests and when
post-processing outputs, and also some of the external supporting
tools have the same or similar capabilities.</p>
<p>In Robot Framework's command line escaping mechanism,
problematic characters are escaped with freely selected text. The
command line option to use is <span class="opt">--escape</span> (short version
<span class="opt">-E</span>), which takes an argument in the format <span class="opt">what:with</span>,
where <span class="opt">what</span> is the name of the character to escape and
<span class="opt">with</span> is the string to escape it with. Characters that can
be escaped are listed in the table below:</p>
<table border="1" class="tabular docutils">
<caption>Available escapes</caption>
<colgroup>
<col width="20%" />
<col width="30%" />
<col width="20%" />
<col width="30%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Character</th>
<th class="head">Name to use</th>
<th class="head">Character</th>
<th class="head">Name to use</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>&amp;</td>
<td>amp</td>
<td>(</td>
<td>paren1</td>
</tr>
<tr><td>'</td>
<td>apos</td>
<td>)</td>
<td>paren2</td>
</tr>
<tr><td>&#64;</td>
<td>at</td>
<td>%</td>
<td>percent</td>
</tr>
<tr><td>\</td>
<td>blash</td>
<td>|</td>
<td>pipe</td>
</tr>
<tr><td>:</td>
<td>colon</td>
<td>?</td>
<td>quest</td>
</tr>
<tr><td>,</td>
<td>comma</td>
<td>&quot;</td>
<td>quot</td>
</tr>
<tr><td>{</td>
<td>curly1</td>
<td>;</td>
<td>semic</td>
</tr>
<tr><td>}</td>
<td>curly2</td>
<td>/</td>
<td>slash</td>
</tr>
<tr><td>$</td>
<td>dollar</td>
<td></td>
<td>space</td>
</tr>
<tr><td>!</td>
<td>exclam</td>
<td>[</td>
<td>square1</td>
</tr>
<tr><td>&gt;</td>
<td>gt</td>
<td>]</td>
<td>square2</td>
</tr>
<tr><td>#</td>
<td>hash</td>
<td>*</td>
<td>star</td>
</tr>
<tr><td>&lt;</td>
<td>lt</td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
<p>The following examples make the syntax more clear. In the
first example, the metadata <span class="opt">X</span> gets the value <span class="code">Value with
spaces</span>, and in the second example variable <span class="var">${VAR}</span> is assigned to
<span class="code">&quot;Hello, world!&quot;</span>:</p>
<pre class="literal-block">
--escape space:_ --metadata X:Value_with_spaces
-E space:SP -E quot:QU -E comma:CO -E exclam:EX -v VAR:QUHelloCOSPworldEXQU
</pre>
<p>Note that all the given command line arguments, including paths to test
data, are escaped. Escape character sequences thus need to be
selected carefully.</p>
</div>
<div class="section" id="argument-files">
<h3><a class="toc-backref" href="#id463">3.1.5&nbsp;&nbsp;&nbsp;Argument files</a></h3>
<p>Problematic characters can often be handled easily using <em>argument files</em>.
These files can contain both command line options and paths
to the test data, one per line. They are taken into use with
<span class="opt">--argumentfile</span> option (short option <span class="opt">-A</span>) along with possible other
command line options.  Argument files can contain any
characters without escaping, but spaces in the beginning and end
of lines are ignored. Additionally, empty lines and lines starting with
a hash mark (#) are ignored:</p>
<pre class="literal-block">
--doc This is an example (where &quot;special characters&quot; are ok!)
--metadata X:Value with spaces
--variable VAR:Hello, world!
# This is a comment
path/to/my/tests
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Starting from Robot Framework 2.5 it is possible to have also non-ASCII
characters in argument files. For this to work, the argument file must
be saved using UTF-8 encoding.</p>
</div>
<p>Another important usage for argument files is specifying input files or
directories in certain order. This can be very useful if the <a class="reference internal" href="#specifying-test-data-to-be-executed">alphabetical
default execution order</a> is not suitable:</p>
<pre class="literal-block">
--name My Example Tests
tests/some_tests.html
tests/second.html
tests/more/tests.html
tests/more/another.html
tests/even_more_tests.html
</pre>
<p>When an argument file is used on the command line, its contents are
placed to the original list of arguments to the same place where the
argument file option was. Argument files can be used either alone so
that they contain all the options and paths to the test data, or along
with other options and paths. It is possible to use <span class="opt">--argumentfile</span>
option multiple times or even recursively:</p>
<pre class="literal-block">
pybot --argumentfile all_arguments.txt
pybot --name example --argumentfile other_options_and_paths.txt
pybot --argumentfile default_options.txt --name example my_tests.html
pybot -A first.txt -A second.txt -A third.txt some_tests.tsv
</pre>
<p>Special value <span class="opt">STDIN</span> can be used to read arguments from the standard
input stream instead of a file. This can be useful when generating arguments
with a script:</p>
<pre class="literal-block">
generate_arguments.sh | pybot --argumentfile STDIN
generate_arguments.sh | pybot --name Example --argumentfile STDIN mytest.txt
</pre>
<p>Reading arguments from the standard input is a new feature in Robot Framework 2.5.6.</p>
</div>
<div class="section" id="getting-help-and-version-information">
<h3><a class="toc-backref" href="#id464">3.1.6&nbsp;&nbsp;&nbsp;Getting help and version information</a></h3>
<p>Both when executing test cases with <span class="prog">pybot</span> or <span class="prog">jybot</span> and
when post-processing reports with <span class="prog">rebot</span>, it is possible to get
command line help with the option <span class="opt">--help</span> and its short version
<span class="opt">-h</span>. These help texts have a short general overview and
briefly explain the available command line options.</p>
<p>All runner scripts also support getting the version information with
the option <span class="opt">--version</span>. This information also contains Python
or Jython version and the platform type:</p>
<pre class="literal-block">
$ pybot --version
Robot Framework 2.0.3 (Python 2.5.1 on cygwin)

C:\&gt;jybot --version
Robot Framework 2.0.3 (Jython 2.2 on java1.5.0_16)

C:\&gt;rebot --version
Rebot 2.0.3 (Python 2.5.2 on win32)
</pre>
</div>
<div class="section" id="creating-start-up-scripts">
<h3><a class="toc-backref" href="#id465">3.1.7&nbsp;&nbsp;&nbsp;Creating start-up scripts</a></h3>
<p>Test cases are often executed automatically by a continuous
integration system or some other mechanism. In such cases, there is a
need to have a script for starting the test execution, and possibly
also for post-processing outputs somehow. Similar scripts are also
useful when running tests manually, especially if a large number of
command line options are needed or setting up the test environment is
complicated.</p>
<p>In UNIX-like environments, shell scripts provide a simple but powerful
mechanism for creating custom start-up scripts. Windows batch files
can also be used, but they are more limited and often also more
complicated. A platform-independent alternative is using Python or
some other high-level programming language. Regardless of the
language, it is recommended that long option names are used, because
they are easier to understand than the short names.</p>
<p>In the first examples, the same web tests are executed with different
browsers and the results combined afterwards. This is easy with shell
scripts, as practically you just list the needed commands one after
another:</p>
<div class="highlight"><pre><span class="c">#!/bin/bash</span>
pybot --variable BROWSER:Firefox --name Firefox --log none --report none --output out/fx.xml login
pybot --variable BROWSER:IE --name IE --log none --report none --output out/ie.xml login
rebot --name Login --outputdir out --output login.xml out/fx.xml out/ie.xml
</pre></div>
<p>Implementing the above example with Windows batch files is not very
complicated, either. The most important thing to remember is that
because <span class="prog">pybot</span> and <span class="prog">rebot</span> are implemented as batch
files, <span class="prog">call</span> must be used when running them from another batch
file. Otherwise execution would end when the first batch file is
finished.</p>
<div class="highlight"><pre><span class="p">@</span><span class="k">echo</span> <span class="k">off</span>
<span class="k">call</span> pybot --variable BROWSER:Firefox --name Firefox --log none --report none --output out\fx.xml login
<span class="k">call</span> pybot --variable BROWSER:IE --name IE --log none --report none --output out\ie.xml login
<span class="k">call</span> rebot --name Login --outputdir out --output login.xml out\fx.xml out\ie.xml
</pre></div>
<p>In the next examples, JAR files under the <span class="path">lib</span> directory are
put into CLASSPATH before starting the test execution. In these
examples, start-up scripts require that paths to the executed test
data are given as arguments. It is also possible to use command line
options freely, even though some options have already been set in the
script. All this is relatively straight-forward using bash:</p>
<div class="highlight"><pre><span class="c">#!/bin/bash</span>

<span class="nv">cp</span><span class="o">=</span>.
<span class="k">for </span>jar in lib/*.jar; <span class="k">do</span>
<span class="k">    </span><span class="nv">cp</span><span class="o">=</span><span class="nv">$cp</span>:<span class="nv">$jar</span>
<span class="k">done</span>
<span class="nb">export </span><span class="nv">CLASSPATH</span><span class="o">=</span><span class="nv">$cp</span>

jybot --ouputdir /tmp/logs --suitestatlevel 2 <span class="nv">$*</span>
</pre></div>
<p>Implementing this using Windows batch files is slightly more complicated. The
difficult part is setting the variable containing the needed JARs inside a For
loop, because, for some reason, that is not possible without a helper
function.</p>
<div class="highlight"><pre><span class="p">@</span><span class="k">echo</span> <span class="k">off</span>

<span class="k">set</span> <span class="nv">CP</span><span class="o">=</span>.
<span class="k">for</span> <span class="nv">%%jar</span> in (lib\*.jar) <span class="k">do</span> (
    <span class="k">call</span> <span class="nl">:set_cp</span> <span class="nv">%%jar</span>
)
<span class="k">set</span> <span class="nv">CLASSPATH</span><span class="o">=</span><span class="nv">%CP%</span>

jybot --ouputdir c:\temp\logs --suitestatlevel <span class="m">2</span> %*

<span class="k">goto</span> <span class="nl">:eof</span>

<span class="c">:: Helper for setting variables inside a for loop</span>
<span class="nl">:set_cp</span>
    <span class="k">set</span> <span class="nv">CP</span><span class="o">=</span><span class="nv">%CP%</span>;<span class="nv">%1</span>
<span class="k">goto</span> <span class="nl">:eof</span>
</pre></div>
<div class="section" id="modifying-java-startup-parameters">
<h4><a class="toc-backref" href="#id466">Modifying Java startup parameters</a></h4>
<p>Sometimes there is need to alter the Java startup parameters. The most
common use case is increasing the JVM maximum memory size as the
default value may not be enough for creating reports and logs when
outputs are very big. How to give the parameters to Java depends on
the Jython version.</p>
<p>With Jython 2.2 you need to modify the Jython start-up script
(<span class="prog">jython</span> shell script or <span class="prog">jython.bat</span> batch file) by
adding the needed options (e.g. <span class="opt">-Xmx1024m</span> which sets the
maximum memory to 1024 megabytes) to the <span class="prog">java</span> command. On
Windows the final command could look like this:</p>
<pre class="literal-block">
&quot;C:\Java\jre1.6.0\bin\java.exe&quot; -Xmx1024m -Dpython.home=&quot;C:\Jython22&quot; -classpath &quot;C:\Jython22\jython.jar;%CLASSPATH%&quot; org.python.util.jython %ARGS%
</pre>
<p>With Jython 2.5 it is also possible, and easier, to give the Java
parameters with <span class="opt">-J</span> option to the Jython interpreter. This means
that you can modify the <span class="prog">jybot</span> start-up script instead of
Jython scripts. The last line of the <span class="prog">jybot</span> script can, again in
Windows, be edited like below:</p>
<pre class="literal-block">
%jython% -J-Xmx1024m %runner% %*
</pre>
</div>
</div>
<div class="section" id="debugging-problems">
<h3><a class="toc-backref" href="#id467">3.1.8&nbsp;&nbsp;&nbsp;Debugging problems</a></h3>
<p>A test case can fail because the system under test does not work
correctly, in which case the test has found a bug, or because the test
itself is buggy. The error message explaining the failure is shown on
the <a class="reference internal" href="#command-line-output">command line output</a> and in the <a class="reference internal" href="#report-file">report file</a>, and sometimes
the error message alone is enough to pinpoint the problem. More often
that not, however, <a class="reference internal" href="#log-file">log files</a> are needed because they have also
other log messages and they show which keyword actually failed.</p>
<p>When a failure is caused by the tested application, the error message
and log messages ought to be enough to understand what caused it. If
that is not the case, the test library does not provide <a class="reference internal" href="#communicating-with-robot-framework">enough
information</a> and needs to be enhanced. In this situation running the
same test manually, if possible, may also reveal more information
about the issue.</p>
<p>Failures caused by test cases themselves or by keywords they use can
sometimes be hard to debug. If the error message, for example, tells
that a keyword is used with wrong number of arguments fixing the
problem is obviously easy, but if a keyword is missing or fails in
unexpected way finding the root cause can be harder. The first place
to look for more information is the <a class="reference internal" href="#errors-and-warnings-during-execution">execution errors</a> section in
the log file. For example, an error about a failed test library import
may well explain why a test has failed due to a missing keyword.</p>
<p>If the log file does not provide enough information by default, it is
possible to execute tests with a lower <a class="reference internal" href="#log-levels">log level</a>. For example
tracebacks showing where in the code the failure occurred are logged
using the <span class="msg">DEBUG</span> level, and this information is invaluable when
the problem is in an individual keyword.</p>
<p>If the log file still does not have enough information, it is a good
idea to enable the <a class="reference internal" href="#system-log">syslog</a> and see what information it provides. It is
also possible to add some keywords to the test cases to see what is
going on. Especially <a class="reference internal" href="#builtin-library">BuiltIn keywords</a> <span class="name">Log</span> and <span class="name">Log
Variables</span> are useful. If nothing else works, it is always possible to
search help from <a class="reference internal" href="#mailing-lists">mailing lists</a> or elsewhere.</p>
</div>
</div>
<div class="section" id="test-execution">
<h2><a class="toc-backref" href="#id444">3.2&nbsp;&nbsp;&nbsp;Test execution</a></h2>
<p>This section describes how the test suite structure created from the parsed
test data is executed, how to continue executing a test case after failures,
and how to stop the whole test execution gracefully.</p>
<div class="contents local topic" id="id138">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#execution-flow" id="id468">3.2.1&nbsp;&nbsp;&nbsp;Execution flow</a><ul>
<li><a class="reference internal" href="#executed-suites-and-tests" id="id469">Executed suites and tests</a></li>
<li><a class="reference internal" href="#setups-and-teardowns" id="id470">Setups and teardowns</a></li>
<li><a class="reference internal" href="#execution-order" id="id471">Execution order</a></li>
</ul>
</li>
<li><a class="reference internal" href="#continue-on-failure" id="id472">3.2.2&nbsp;&nbsp;&nbsp;Continue on failure</a><ul>
<li><a class="reference internal" href="#special-failures-from-keywords" id="id473">Special failures from keywords</a></li>
<li><a class="reference internal" href="#run-keyword-and-continue-on-failure-keyword" id="id474"><span class="name">Run Keyword And Continue On Failure</span> keyword</a></li>
<li><a class="reference internal" href="#execution-continues-on-teardowns-automatically" id="id475">Execution continues on teardowns automatically</a></li>
<li><a class="reference internal" href="#all-top-level-keywords-are-executed-when-tests-have-templates" id="id476">All top-level keywords are executed when tests have templates</a></li>
</ul>
</li>
<li><a class="reference internal" href="#stopping-test-execution-gracefully" id="id477">3.2.3&nbsp;&nbsp;&nbsp;Stopping test execution gracefully</a><ul>
<li><a class="reference internal" href="#pressing-ctrl-c" id="id478">Pressing <span class="code">Ctrl-C</span></a></li>
<li><a class="reference internal" href="#using-signals" id="id479">Using signals</a></li>
<li><a class="reference internal" href="#using-keywords" id="id480">Using keywords</a></li>
<li><a class="reference internal" href="#exitonfailure-mode" id="id481"><span class="opt">ExitOnFailure</span> mode</a></li>
<li><a class="reference internal" href="#handling-teardowns" id="id482">Handling teardowns</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="execution-flow">
<h3><a class="toc-backref" href="#id468">3.2.1&nbsp;&nbsp;&nbsp;Execution flow</a></h3>
<div class="section" id="executed-suites-and-tests">
<h4><a class="toc-backref" href="#id469">Executed suites and tests</a></h4>
<p>Test cases are always executed within a test suite. A test suite
created from a <a class="reference internal" href="#test-case-files">test case file</a> has tests directly, whereas suites
created from <a class="reference internal" href="#test-suite-directories">directories</a> have child test suites which either have
tests or their own child suites. By default all the tests in an
executed suite are run, but it is possible to <a class="reference internal" href="#selecting-test-cases">select tests</a> using
options <span class="opt">--test</span>, <span class="opt">--suite</span>, <span class="opt">--include</span> and
<span class="opt">--exclude</span>. Suites containing no tests are ignored.</p>
<p>The execution starts from the top-level test suite. If the suite has
tests they are executed one-by-one, and if it has suites they are
executed recursively in depth-first order. When an individual test
case is executed, the keywords it contains are run in a
sequence. Normally the execution of the current test ends if any
of the keywords fails, but it is also possible to
<a class="reference internal" href="#continue-on-failure">continue after failures</a>. The exact <a class="reference internal" href="#execution-order">execution order</a> and how
possible <a class="reference internal" href="#setups-and-teardowns">setups and teardowns</a> affect the execution are discussed
in the following sections.</p>
</div>
<div class="section" id="setups-and-teardowns">
<h4><a class="toc-backref" href="#id470">Setups and teardowns</a></h4>
<p>Setups and teardowns can be defined on <a class="reference internal" href="#test-setup-and-teardown">test case</a> and <a class="reference internal" href="#suite-setup-and-teardown">test suite</a> level.</p>
<div class="section" id="suite-setup">
<h5>Suite setup</h5>
<p>If a test suite has a setup, it is executed before its tests and child
suites. If the suite setup passes, test execution continues
normally. If it fails, all the test cases the suite and its child
suites are marked failed with a message <span class="msg">Setup of the parent
suite failed.</span>. The tests and possible suite setups and teardowns in
the child test suites are not executed.</p>
<p>Suite setups are often used for setting up the test environment.
Because tests are not run if the suite setup fails, it is easy to use
suite setups for verifying that the environment is in state in which the
tests can be executed.</p>
</div>
<div class="section" id="suite-teardown">
<h5>Suite teardown</h5>
<p>If a test suite has a teardown, it is executed after all its test
cases and child suites. Suite teardowns are executed regardless of the
test status and even if the matching suite setup fails. If the suite
teardown fails, all tests in the suite are marked failed afterwards in
reports and logs.</p>
<p>Suite teardowns are mostly used for cleaning up the test environment
after the execution. To ensure that all these tasks are done, <a class="reference internal" href="#continue-on-failure">all the
keywords used in the teardown are executed</a> even if some of them
fail.</p>
</div>
<div class="section" id="test-setup">
<h5>Test setup</h5>
<p>Possible test setup is executed before the keywords of the test case.
If the setup fails, the keywords are not executed. The main use
for test setups is setting up the environment for that particular test
case.</p>
</div>
<div class="section" id="test-teardown">
<h5>Test teardown</h5>
<p>Possible test teardown is executed after the test case has been
executed. It is executed regardless of the test status and also
if the setup of the test has failed.</p>
<p>Similarly as suite teardown, test teardowns are used mainly for
cleanup activities. Also they are executed fully even if some of their
keywords fail.</p>
</div>
</div>
<div class="section" id="execution-order">
<h4><a class="toc-backref" href="#id471">Execution order</a></h4>
<p>Test cases in a test suite are executed in the same order as they are defined
in the test case file. Test suites inside a higher level test suite are
executed in case-insensitive alphabetical order based on the file or directory
name. If multiple files and/or directories are given from the command line,
they are executed in the order they are given.</p>
<p>If there is a need to use certain test suite execution order inside a
directory, it is possible to add prefixes like <span class="path">01</span> and
<span class="path">02</span> into file and directory names. Such prefixes are not
included in the generated test suite name if they are separated from
the base name of the suite with two underscores:</p>
<pre class="literal-block">
01__my_suite.html -&gt; My Suite
02__another_suite.html -&gt; Another Suite
</pre>
<p>If the alphabetical ordering of test suites inside suites is
problematic, a good workaround is giving them separately in the
required order. This easily leads to overly long start-up commands,
but <a class="reference internal" href="#argument-files">argument files</a> allow listing files nicely one file per line.</p>
<p>It is also possible to <a class="reference internal" href="#randomizing-execution-order">randomize the execution order</a> using
the <span class="opt">--runmode</span> option.</p>
</div>
</div>
<div class="section" id="continue-on-failure">
<h3><a class="toc-backref" href="#id472">3.2.2&nbsp;&nbsp;&nbsp;Continue on failure</a></h3>
<p>Normally test cases are stopped immediately when any of their keywords
fail. This behavior shortens test execution time and prevents
subsequent keywords hanging or otherwise causing problems if the
system under test is in unstable state. This has the drawback that often
subsequent keywords would give more information about the state of the
system.</p>
<p>Before Robot Framework 2.5 the only way to handle failures so that
test execution is not terminated immediately was using <a class="reference internal" href="#builtin-library">BuiltIn
keywords</a> <span class="name">Run Keyword And Ignore Error</span> and <span class="name">Run Keyword
And Expect Error</span>. Using these keywords for this purpose often added
extra complexity to test cases, and in Robot Framework 2.5 the
following features were added to make continuing after failures
easier.</p>
<div class="section" id="special-failures-from-keywords">
<h4><a class="toc-backref" href="#id473">Special failures from keywords</a></h4>
<p><a class="reference internal" href="#using-test-libraries">Library keywords</a> report failures using exceptions, and it is
possible to use special exceptions to tell the core framework that
execution can continue regardless the failure. How these exceptions
can be created is explained in the <a class="reference internal" href="#continuing-test-execution-despite-of-failures">test library API chapter</a>.</p>
<p>When a test ends and there has been one or more continuable failure,
the test will be marked failed. If there are more than one failure,
all of them will be enumerated in the final error message:</p>
<pre class="literal-block">
Several failures occurred:

1) First error message.

2) Second error message ...
</pre>
<p>Test execution ends also if a normal failure occurs after continuable
failures. Also in that case all the failures will be listed in the
final error message.</p>
<p>The return value from failed keywords, possibly assigned to a
variable, is always the Python <span class="code">None</span>.</p>
</div>
<div class="section" id="run-keyword-and-continue-on-failure-keyword">
<h4><a class="toc-backref" href="#id474"><span class="name">Run Keyword And Continue On Failure</span> keyword</a></h4>
<p><a class="reference internal" href="#builtin-library">BuiltIn keyword</a> <span class="name">Run Keyword And Continue On Failure</span> allows
converting any failure into a continuable failure. These failures are
handled by the framework exactly the same way as continuable failures
originating from library keywords.</p>
</div>
<div class="section" id="execution-continues-on-teardowns-automatically">
<h4><a class="toc-backref" href="#id475">Execution continues on teardowns automatically</a></h4>
<p>To make it sure that all the cleanup activities are taken care of, the
continue on failure mode is automatically on in <a class="reference internal" href="#setups-and-teardowns">test and suite
teardowns</a>. In practice this means that in teardowns all the
keywords in all levels are always executed.</p>
</div>
<div class="section" id="all-top-level-keywords-are-executed-when-tests-have-templates">
<h4><a class="toc-backref" href="#id476">All top-level keywords are executed when tests have templates</a></h4>
<p>When using <a class="reference internal" href="#test-templates">test templates</a>, all the data rows are always executed to
make it sure that all the different combinations are tested. In this
usage continuing is limited to the top-level keywords, and inside them
the execution ends normally if there are non-continuable failures.</p>
</div>
</div>
<div class="section" id="stopping-test-execution-gracefully">
<h3><a class="toc-backref" href="#id477">3.2.3&nbsp;&nbsp;&nbsp;Stopping test execution gracefully</a></h3>
<p>Sometimes there is a need to stop the test execution before all the tests
have finished, but so that logs and reports are created. Different ways how
to accomplish this are explained below. In all these cases the remaining
test cases are marked failed.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Most of these features are new in Robot Framework 2.5. Only
the <a class="reference internal" href="#exitonfailure-mode">ExitOnFailure mode</a> is supported in earlier versions.</p>
</div>
<div class="section" id="pressing-ctrl-c">
<h4><a class="toc-backref" href="#id478">Pressing <span class="code">Ctrl-C</span></a></h4>
<p>The execution is stopped when <span class="code">Ctrl-C</span> is pressed in the console
where the tests are running. When running the tests on Python, the
execution is stopped immediately, but with Jython it ends only after
the currently executing keyword ends.</p>
<p>If <span class="code">Ctrl-C</span> is pressed again, the execution ends immediately and
reports and logs are not created.</p>
</div>
<div class="section" id="using-signals">
<h4><a class="toc-backref" href="#id479">Using signals</a></h4>
<p>On Unix-like machines it is possible to terminate test execution
using signals <span class="code">INT</span> and <span class="code">TERM</span>. These signals can be sent
from the command line using <span class="prog">kill</span> command, and sending signals can
also be easily automated.</p>
<p>Signals have the same limitation on Jython as pressing <span class="code">Ctrl-C</span>.
Similarly also the second signal stops the execution forcefully.</p>
</div>
<div class="section" id="using-keywords">
<h4><a class="toc-backref" href="#id480">Using keywords</a></h4>
<p>The execution can be stopped also by the executed keywords. There is a
separate <span class="name">Fatal Error</span> <a class="reference internal" href="#builtin-library">BuiltIn keyword</a> for this purpose, and
custom keywords can use <a class="reference internal" href="#stopping-test-execution">fatal exceptions</a> when they fail.</p>
</div>
<div class="section" id="exitonfailure-mode">
<h4><a class="toc-backref" href="#id481"><span class="opt">ExitOnFailure</span> mode</a></h4>
<p>If option <span class="opt">--runmode</span> is used with value <span class="opt">ExitOnFailure</span>
(case-insensitive), the execution of tests stops immediately if
a <a class="reference internal" href="#setting-criticality">critical test</a> fails and the remaining tests are marked as failed.</p>
</div>
<div class="section" id="handling-teardowns">
<h4><a class="toc-backref" href="#id482">Handling teardowns</a></h4>
<p>By default teardowns for tests and suites that have been started are executed
even if test execution is stopped using one of the methods above. This allows
clean-up activities to be run regardless how execution ends.</p>
<p>Starting from Robot Framework 2.5.2, teardowns are skipped when the execution is
stopped if the <span class="opt">--runmode SkipTeardownOnExit</span> command line option is used.
This can be useful if clean-up takes a lot of time.</p>
</div>
</div>
</div>
<div class="section" id="post-processing-outputs">
<h2><a class="toc-backref" href="#id445">3.3&nbsp;&nbsp;&nbsp;Post-processing outputs</a></h2>
<p><a class="reference internal" href="#output-file">XML output files</a> that are generated during the test execution can be
post-processed afterwards by the <span class="prog">rebot</span> tool, which is an integral
part of Robot Framework. It is used automatically when test
reports and logs are generated during the test execution, but there
are also good grounds for using it separately after the execution.</p>
<div class="contents local topic" id="id149">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#using-rebot-tool" id="id483">3.3.1&nbsp;&nbsp;&nbsp;Using <span class="prog">rebot</span> tool</a></li>
<li><a class="reference internal" href="#creating-different-reports-and-logs" id="id484">3.3.2&nbsp;&nbsp;&nbsp;Creating different reports and logs</a></li>
<li><a class="reference internal" href="#combining-outputs" id="id485">3.3.3&nbsp;&nbsp;&nbsp;Combining outputs</a></li>
</ul>
</div>
<div class="section" id="using-rebot-tool">
<h3><a class="toc-backref" href="#id483">3.3.1&nbsp;&nbsp;&nbsp;Using <span class="prog">rebot</span> tool</a></h3>
<p>The basic syntax for using <span class="prog">rebot</span> is exactly the same as when
<a class="reference internal" href="#starting-test-execution">starting test execution</a>, <a class="reference internal" href="#return-codes">return codes</a> are the same, and also
most of the command line options are identical. The main difference is
that arguments to <span class="prog">rebot</span> are XML output files instead of test
data files or directories.</p>
</div>
<div class="section" id="creating-different-reports-and-logs">
<h3><a class="toc-backref" href="#id484">3.3.2&nbsp;&nbsp;&nbsp;Creating different reports and logs</a></h3>
<p>You can use <span class="prog">rebot</span> for creating the same reports and logs that
are created automatically during the test execution. Of course, it is
not sensible to create the exactly same files, but, for example,
having one report with all test cases and another with only some
subset of tests can be useful. Another common usage is creating only
the output file when running tests (log and report generation can be
disabled with options <span class="opt">--log NONE</span> and <span class="opt">--report NONE</span>) and
generating logs and reports later. Tests can, for example, be executed
on different environments, output files collected to a central place,
and reports and logs created there. If generating reports and logs
takes a lot of time when running tests on Jython, it is a good idea to
try if using <span class="prog">rebot</span>, which always runs on Python, is any
faster.</p>
<pre class="literal-block">
rebot output.xml
rebot path/to/output_file.xml
rebot --include smoke --name Smoke_Tests c:\results\output.xml
</pre>
<p>When using Robot Framework jar distribution, <span class="prog">rebot</span> is started with command:</p>
<pre class="literal-block">
java -jar robotframework-&lt;version&gt;.jar rebot
</pre>
<p>All normal command line options can be used when executing <span class="prog">rebot</span> from jar.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">When running tests with Jython, the default JVM maximum
memory size may not be enough for creating reports and logs
if output files are very large. If that happens, you can
either <a class="reference internal" href="#modifying-java-startup-parameters">increase the JVM's maximum memory</a>, or disable
creating reports and logs when tests are executed and use
<span class="prog">rebot</span> to generate them afterwards.</p>
</div>
</div>
<div class="section" id="combining-outputs">
<h3><a class="toc-backref" href="#id485">3.3.3&nbsp;&nbsp;&nbsp;Combining outputs</a></h3>
<p>The most important feature of <span class="prog">rebot</span> is its ability to combine
outputs from different test execution rounds. This capability allows,
for example, running the same test cases on different environments and
generating an overall report from all outputs. Combining outputs is
extremely easy, all that needs to be done is giving several output
files as arguments:</p>
<pre class="literal-block">
rebot output1.xml output2.xml
rebot outputs/*.xml
</pre>
<p>When outputs are combined, a new top-level test suite is created so
that test suites in the given output files are its child suites. This
works the same way when <a class="reference internal" href="#specifying-test-data-to-be-executed">multiple test data files or directories are
executed</a>, and also in this case the name of the top-level test
suite is created by joining child suite names with an ampersand (&amp;)
and spaces. These automatically generated names are not that good, and
it is often a good idea to use <span class="opt">--name</span> to give a more
meaningful name:</p>
<pre class="literal-block">
rebot --name Browser_Compatibility firefox.xml opera.xml safari.xml ie.xml
rebot --include smoke --name Smoke_Tests c:\results\*.xml
</pre>
</div>
</div>
<div class="section" id="configuring-execution">
<h2><a class="toc-backref" href="#id446">3.4&nbsp;&nbsp;&nbsp;Configuring execution</a></h2>
<p>This section explains different command line options that can be used
for configuring the <a class="reference internal" href="#starting-test-execution">test execution</a> or <a class="reference internal" href="#post-processing-outputs">post-processing
outputs</a>. Options related to generated output files are discussed in
the <a class="reference internal" href="#created-outputs">next section</a>.</p>
<div class="contents local topic" id="id153">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#selecting-test-cases" id="id486">3.4.1&nbsp;&nbsp;&nbsp;Selecting test cases</a><ul>
<li><a class="reference internal" href="#by-test-suite-and-test-case-names" id="id487">By test suite and test case names</a></li>
<li><a class="reference internal" href="#by-tag-names" id="id488">By tag names</a></li>
<li><a class="reference internal" href="#when-no-tests-match-selection" id="id489">When no tests match selection</a></li>
</ul>
</li>
<li><a class="reference internal" href="#setting-criticality" id="id490">3.4.2&nbsp;&nbsp;&nbsp;Setting criticality</a></li>
<li><a class="reference internal" href="#setting-metadata" id="id491">3.4.3&nbsp;&nbsp;&nbsp;Setting metadata</a><ul>
<li><a class="reference internal" href="#setting-the-name" id="id492">Setting the name</a></li>
<li><a class="reference internal" href="#setting-the-documentation" id="id493">Setting the documentation</a></li>
<li><a class="reference internal" href="#setting-free-metadata" id="id494">Setting free metadata</a></li>
<li><a class="reference internal" href="#setting-tags" id="id495">Setting tags</a></li>
</ul>
</li>
<li><a class="reference internal" href="#adjusting-library-search-path" id="id496">3.4.4&nbsp;&nbsp;&nbsp;Adjusting library search path</a><ul>
<li><a class="reference internal" href="#locations-automatically-in-pythonpath" id="id497">Locations automatically in PYTHONPATH</a></li>
<li><a class="reference internal" href="#setting-pythonpath" id="id498">Setting PYTHONPATH</a></li>
<li><a class="reference internal" href="#setting-classpath" id="id499">Setting CLASSPATH</a></li>
<li><a class="reference internal" href="#using-pythonpath-option" id="id500">Using --pythonpath option</a></li>
</ul>
</li>
<li><a class="reference internal" href="#setting-variables" id="id501">3.4.5&nbsp;&nbsp;&nbsp;Setting variables</a></li>
<li><a class="reference internal" href="#dry-run" id="id502">3.4.6&nbsp;&nbsp;&nbsp;Dry run</a></li>
<li><a class="reference internal" href="#randomizing-execution-order" id="id503">3.4.7&nbsp;&nbsp;&nbsp;Randomizing execution order</a></li>
<li><a class="reference internal" href="#controlling-console-output" id="id504">3.4.8&nbsp;&nbsp;&nbsp;Controlling console output</a><ul>
<li><a class="reference internal" href="#console-width" id="id505">Console width</a></li>
<li><a class="reference internal" href="#console-colors" id="id506">Console colors</a></li>
</ul>
</li>
<li><a class="reference internal" href="#setting-listeners" id="id507">3.4.9&nbsp;&nbsp;&nbsp;Setting listeners</a></li>
</ul>
</div>
<div class="section" id="selecting-test-cases">
<h3><a class="toc-backref" href="#id486">3.4.1&nbsp;&nbsp;&nbsp;Selecting test cases</a></h3>
<p>Robot Framework offers several command line options for selecting
which test cases to execute. The same options also work when
post-processing outputs with the <span class="prog">rebot</span> tool.</p>
<div class="section" id="by-test-suite-and-test-case-names">
<h4><a class="toc-backref" href="#id487">By test suite and test case names</a></h4>
<p>Test suites and test cases can be selected by their names with the command
line options <span class="opt">--suite (-s)</span> and <span class="opt">--test (-t)</span>,
respectively.  Both of these options can be used several times to
select several test suites or cases. Arguments to these options are
case- and space-insensitive, and there can also be <a class="reference internal" href="#option-value-as-simple-pattern">simple
patterns</a> matching multiple names.  If both the <span class="opt">--suite</span> and
<span class="opt">--test</span> options are used, only test cases in matching suites
with matching names are selected.</p>
<pre class="literal-block">
--test Example
--test mytest --test yourtest
--test example*
--test mysuite.mytest
--test *.suite.mytest
--suite example-??
--suite mysuite --test mytest --test your*
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Selecting test cases using long name (e.g. <span class="name">mysuite.mytest</span>)
works with Robot Framework 2.5.6 and newer.</p>
</div>
<p>Using the <span class="opt">--suite</span> option is more or less the same as executing only
the appropriate test case file or directory. One major benefit is the
possibility to select the suite based on its parent suite. The syntax
for this is specifying both the parent and child suite names separated
with a dot. In this case, the possible setup and teardown of the parent
suite are executed.</p>
<pre class="literal-block">
--suite parent.child
--suite myhouse.myhousemusic --test jack*
</pre>
<p>Selecting individual test cases with the <span class="opt">--test</span> option is very
practical when creating test cases, but quite limited when running tests
automatically. The <span class="opt">--suite</span> option can be useful in that
case, but in general, selecting test cases by tag names is more
flexible.</p>
</div>
<div class="section" id="by-tag-names">
<h4><a class="toc-backref" href="#id488">By tag names</a></h4>
<p>It is possible to include and exclude test cases by <a class="reference internal" href="#tagging-test-cases">tag</a> names with the
<span class="opt">--include (-i)</span> and <span class="opt">--exclude (-e)</span> options,
respectively. When the former is used, only test cases having a
matching tag are selected, and with the latter, test cases having a
matching tag are not. If both are used, only tests with a tag
matching the former option, and not with a tag matching the latter,
are selected.</p>
<pre class="literal-block">
--include example
--exclude not_ready
--include regression --exclude long_lasting
</pre>
<p>Both <span class="opt">--include</span> and <span class="opt">--exclude</span> can be used several
times to match multiple tags, and their arguments can be <a class="reference internal" href="#option-value-as-simple-pattern">simple
patterns</a>. In these cases, the rules for selecting test cases apply,
so that test cases with a tag matching any include patterns are
selected, and tests with a tag matching exclude patterns are not. It
is also possible to select only test cases that have two or more
specified tags by separating the tags either with <span class="code">&amp;</span> or
<span class="code">AND</span> (case-sensitive). Starting from Robot Framework 2.1.3, only tests
with a certain tag, but without any others, can be selected by separating these
tags with <span class="code">NOT</span> (case-sensitive). If any of the patterns between
multiple <span class="code">NOT</span> is matching, the test case is not selected.</p>
<pre class="literal-block">
--include req-*
--include regressionANDiter-42
--include tag1&amp;tag2&amp;tag3&amp;tag4
--exclude regressionNOTowner-*
--include tag1NOTtag2NOTtag3&amp;tag4  (includes tests which have `tag1`, but not tests which additionally have `tag2` or both tags `tag3` and `tag4`)
</pre>
<p>Selecting test cases by tags is a very flexible mechanism and allows
many interesting possibilities:</p>
<ul class="simple">
<li>A subset of tests to be executed before other tests can be tagged
with <span class="opt">smoke</span> and executed with <span class="cli">--include smoke</span>.</li>
<li>Unfinished test can be committed to version control with the tag
<span class="opt">not_ready</span> and excluded from the test execution with
<span class="cli">--exclude not_ready</span>.</li>
<li>Tests can be tagged with <span class="opt">iter-&lt;num&gt;</span>, where
<span class="opt">&lt;num&gt;</span> specifies the number of the current iteration, and
after executing all test cases, a separate report containing only
the tests for a certain iteration can be generated (for example, <span class="cli">rebot
--include iter-42 output.xml</span>).</li>
</ul>
</div>
<div class="section" id="when-no-tests-match-selection">
<h4><a class="toc-backref" href="#id489">When no tests match selection</a></h4>
<p>By default when no tests match the selection criteria the execution fails
with an error like:</p>
<pre class="literal-block">
[ ERROR ] Suite 'Example' with includes 'xxx' contains no test cases.
</pre>
<p>Because no outputs are generated, this behavior can be problematic if tests
are executed and results processed automatically. Luckily a command line
option <span class="opt">--RunEmptySuite</span> can be used to force the suite to be executed
also in this case. As a result normal outputs are created but show zero
executed tests.</p>
<p>The same option can be used also to alter the behavior when an empty
directory or a test case file containing no tests is executed.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This is a new option in Robot Framework 2.6.</p>
</div>
</div>
</div>
<div class="section" id="setting-criticality">
<h3><a class="toc-backref" href="#id490">3.4.2&nbsp;&nbsp;&nbsp;Setting criticality</a></h3>
<p>The final result of test execution is determined on the basis of
critical tests. If a single critical test fails, the whole test run is
considered failed. On the other hand, non-critical test cases can
fail and the overall status is still passed.</p>
<p>By default, all test cases are critical, but this can be changed with
the <span class="opt">--critical (-c)</span> and <span class="opt">--noncritical (-n)</span>
options. These options specify which test cases are consider critical
based on tags, similarly as <span class="opt">--include</span> and
<span class="opt">--exclude</span> are used to <a class="reference internal" href="#by-tag-names">select test cases by tag
names</a>. If only <span class="opt">--critical</span> is used, test cases with a
matching tag are critical. If only <span class="opt">--noncritical</span> is used,
tests without a matching tag are critical. Finally, if both are
used, only test with a critical tag but without a non-critical tag are
considered critical.  Both of these options accept <a class="reference internal" href="#option-value-as-simple-pattern">simple patterns</a>
and can be given several times:</p>
<pre class="literal-block">
--critical regression
--noncritical not_ready
--critical iter-* --critical req-* --noncritical req-6??
</pre>
<p>The most common use case for setting criticality is having test cases
that are not ready or test features still under development in the
test execution. Of course, these tests could be excluded from the
test execution altogether with the <span class="opt">--exclude</span> option, but
including them as non-critical tests enables you to see when
they start to pass.</p>
<p><a class="reference external" href="http://code.google.com/p/robotframework/issues/detail?id=146">Starting from Robot Framework 2.1</a> criticality set when tests are
executed is not stored anywhere. If you want to keep same criticality
when <a class="reference internal" href="#post-processing-outputs">post-processing outputs</a> with <span class="prog">rebot</span>, you need to
use <span class="opt">--critical</span> and/or <span class="opt">--noncritical</span> also with it:</p>
<pre class="literal-block">
# Use rebot to create new log and report from the output created during execution
pybot --critical regression --outputdir all my_tests.html
rebot --name Smoke --include smoke --critical regression --outputdir smoke all/output.xml

# No need to use --critical/--noncritical when no log or report is created
jybot --log NONE --report NONE my_tests.html
rebot --critical feature1 output.xml
</pre>
</div>
<div class="section" id="setting-metadata">
<h3><a class="toc-backref" href="#id491">3.4.3&nbsp;&nbsp;&nbsp;Setting metadata</a></h3>
<div class="section" id="setting-the-name">
<h4><a class="toc-backref" href="#id492">Setting the name</a></h4>
<p>When Robot Framework parses test data, <a class="reference internal" href="#test-suite-name-and-documentation">test suite names are created
from file and directory names</a>. The name of the top-level test suite
can, however, be overridden with the command line option
<span class="opt">--name (-N)</span>. Underscores in the given name are converted to
spaces automatically, and words in the name capitalized.</p>
</div>
<div class="section" id="setting-the-documentation">
<h4><a class="toc-backref" href="#id493">Setting the documentation</a></h4>
<p>In addition to <a class="reference internal" href="#test-suite-name-and-documentation">defining documentation in the test data</a>, documentation
of the top-level suite can be given from the command line with the
option <span class="opt">--doc (-D)</span>. Underscores in the given documentation
are converted to spaces, and it may contain simple <a class="reference internal" href="#documentation-formatting">HTML formatting</a>.</p>
</div>
<div class="section" id="setting-free-metadata">
<h4><a class="toc-backref" href="#id494">Setting free metadata</a></h4>
<p><a class="reference internal" href="#free-test-suite-metadata">Free test suite metadata</a> may also be given from the command line with the
option <span class="opt">--metadata (-M)</span>. The argument must be in the format
<span class="opt">name:value</span>, where <span class="opt">name</span> the name of the metadata to set and
<span class="opt">value</span> is its value. Underscores in the name and value are converted to
spaces, and the latter may contain simple <a class="reference internal" href="#documentation-formatting">HTML formatting</a>. This option may
be used several times to set multiple metadata.</p>
</div>
<div class="section" id="setting-tags">
<h4><a class="toc-backref" href="#id495">Setting tags</a></h4>
<p>The command line option <span class="opt">--settag (-G)</span> can be used to set
the given tag to all executed test cases. This option may be used
several times to set multiple tags.</p>
</div>
</div>
<div class="section" id="adjusting-library-search-path">
<h3><a class="toc-backref" href="#id496">3.4.4&nbsp;&nbsp;&nbsp;Adjusting library search path</a></h3>
<p>When a <a class="reference internal" href="#taking-test-libraries-into-use">test library is taken into use</a>, Robot Framework uses the Python
or Jython interpreter to import a module implementing the library from
the system. The location where these modules are searched from is called
PYTHONPATH, and when running tests on Jython, also Java CLASSPATH is
used.</p>
<p>Adjusting the library search path so that libraries are found is
a requirement for successful test execution. In addition to
find test libraries, the search path is also used to find <a class="reference internal" href="#setting-listeners">listeners
set on the command line</a>. There are various ways to alter
PYTHONPATH and CLASSPATH, but regardless of the selected approach, it is
recommended to use a <a class="reference internal" href="#creating-start-up-scripts">custom start-up script</a>.</p>
<div class="section" id="locations-automatically-in-pythonpath">
<h4><a class="toc-backref" href="#id497">Locations automatically in PYTHONPATH</a></h4>
<p>Python and Jython installations put their own library directories into
PYTHONPATH automatically. This means that test libraries <a class="reference internal" href="#packaging-libraries">packaged
using Python's own packaging system</a> are automatically installed
into a location that is in the library search path. Robot Framework
also puts the directory containing its <a class="reference internal" href="#standard-libraries">standard libraries</a> and the
directory where tests are executed from into PYTHONPATH.</p>
</div>
<div class="section" id="setting-pythonpath">
<h4><a class="toc-backref" href="#id498">Setting PYTHONPATH</a></h4>
<p>There are several ways to alter PYTHONPATH in the system, but the most
common one is setting an environment variable with the same name
before the test execution. Jython actually does not use PYTHONPATH
environment variable normally, but Robot Framework ensures that
locations listed in it are added into the library search path
regardless of the interpreter.</p>
</div>
<div class="section" id="setting-classpath">
<h4><a class="toc-backref" href="#id499">Setting CLASSPATH</a></h4>
<p>CLASSPATH is used only with Jython, and the most common way to alter
it is setting an environment variable similarly as with PYTHONPATH.
Note that instead of CLASSPATH, it is always possible to use
PYTHONPATH with Jython, even with libraries and listeners implemented
with Java.</p>
</div>
<div class="section" id="using-pythonpath-option">
<h4><a class="toc-backref" href="#id500">Using --pythonpath option</a></h4>
<p>Robot Framework also has a separate command line option
<span class="opt">--pythonpath (-P)</span> for adding directories or archives into
PYTHONPATH. Multiple paths can be given by separating them with a
colon (:) or using this option several times. The given path can also be
a glob pattern matching multiple paths, but then it normally must be
<a class="reference internal" href="#escaping-complicated-characters">escaped</a>.</p>
<p>Examples:</p>
<pre class="literal-block">
--pythonpath libs/
--pythonpath /opt/testlibs:mylibs.zip:yourlibs
--pythonpath mylib.jar --pythonpath lib/STAR.jar --escape star:STAR
</pre>
</div>
</div>
<div class="section" id="setting-variables">
<h3><a class="toc-backref" href="#id501">3.4.5&nbsp;&nbsp;&nbsp;Setting variables</a></h3>
<p><a class="reference internal" href="#variables">Variables</a> can be set from the command line either <a class="reference internal" href="#setting-variables-in-command-line">individually</a>
using the <span class="opt">--variable (-v)</span> option or through <a class="reference internal" href="#variable-files">variable files</a>
with the <span class="opt">--variablefile (-V)</span> option. Variables and variable
files are explained in separate chapters, but the following examples
illustrate how to use these options:</p>
<pre class="literal-block">
--variable name:value
--variable OS:Linux --variable IP:10.0.0.42
--variablefile path/to/variables.py
--variablefile myvars.py:possible:arguments:here
--variable ENVIRONMENT:Windows --variablefile c:\resources\windows.py
</pre>
</div>
<div class="section" id="dry-run">
<h3><a class="toc-backref" href="#id502">3.4.6&nbsp;&nbsp;&nbsp;Dry run</a></h3>
<p>Robot Framework supports so called <em>dry run</em> mode where the tests are
run normally otherwise, but the keywords coming from the test libraries
are not executed at all. The dry run mode can be used to validate the
test data; if the dry run passes, the data should be syntactically
correct.  This mode is triggered using option <span class="opt">--runmode DryRun</span>
(case-insensitive) and it is supported starting from Robot Framework
2.5.</p>
<p>The dry run execution may fail for following reasons:</p>
<blockquote>
<ul class="simple">
<li>Using keywords that are not found.</li>
<li>Using keywords with wrong number of arguments.</li>
<li>Using user keywords that have invalid syntax.</li>
</ul>
</blockquote>
<p>In addition to these failures, normal <a class="reference internal" href="#errors-and-warnings-during-execution">execution errors</a> are shown,
for example, when test library or resource file imports cannot be
resolved.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The dry run mode does not validate variables. This
limitation may be lifted in the future releases.</p>
</div>
</div>
<div class="section" id="randomizing-execution-order">
<h3><a class="toc-backref" href="#id503">3.4.7&nbsp;&nbsp;&nbsp;Randomizing execution order</a></h3>
<p>The <span class="opt">--runmode</span> option can also be used to randomize the test
execution order. This is done using the different values explained
below.</p>
<dl class="docutils">
<dt><span class="opt">random:test</span></dt>
<dd>Test cases inside each test suite are executed in random
order.</dd>
<dt><span class="opt">random:suite</span></dt>
<dd>All test suites are executed in a random order, but test cases inside
suites are run in the order they are defined.</dd>
<dt><span class="opt">random:all</span></dt>
<dd>Both test cases and test suites are executed in a random
order.</dd>
</dl>
<p>Example:</p>
<pre class="literal-block">
pybot --runmode random:test my_test.txt
</pre>
</div>
<div class="section" id="controlling-console-output">
<h3><a class="toc-backref" href="#id504">3.4.8&nbsp;&nbsp;&nbsp;Controlling console output</a></h3>
<div class="section" id="console-width">
<h4><a class="toc-backref" href="#id505">Console width</a></h4>
<p>The width of the test execution output in the console can be set using
the option <span class="opt">--monitorwidth (-W)</span>. The default width is 78 characters.</p>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p class="last">On many UNIX-like machines you can use handy <span class="var">$COLUMNS</span>
variable like <span class="cli">--monitorwidth $COLUMNS</span>.</p>
</div>
</div>
<div class="section" id="console-colors">
<h4><a class="toc-backref" href="#id506">Console colors</a></h4>
<p>The <span class="opt">--monitorcolors (-C)</span> option is used to control whether
colors should be used in the console output. Colors should work on all
other platforms except for Windows when using Jython. This option has
following case-insensitive values:</p>
<dl class="docutils">
<dt><span class="opt">auto</span></dt>
<dd>Colors are enabled when output is written into the console but
not when it is redirected into a file. This is the default and there
is rarely need to change it.</dd>
<dt><span class="opt">on</span></dt>
<dd>Colors are used also when output is redirected into a file.
Does not have effect on Windows.</dd>
<dt><span class="opt">off</span></dt>
<dd>Colors are disabled.</dd>
<dt><span class="opt">force</span></dt>
<dd>Backwards compatibility with Robot Framework 2.5.5 and older.
Should not be used.</dd>
</dl>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Support for colors on Windows and the <span class="opt">auto</span> mode are
new features in Robot Framework 2.5.6.</p>
</div>
</div>
</div>
<div class="section" id="setting-listeners">
<h3><a class="toc-backref" href="#id507">3.4.9&nbsp;&nbsp;&nbsp;Setting listeners</a></h3>
<p>So-called <a class="reference internal" href="#using-listener-interface">listeners</a> can be used for monitoring the test
execution. They are taken into use with the command line option
<span class="opt">--listener</span>, and the specified listeners must be in the <a class="reference internal" href="#adjusting-library-search-path">module
search path</a> similarly as test libraries.</p>
</div>
</div>
<div class="section" id="created-outputs">
<h2><a class="toc-backref" href="#id447">3.5&nbsp;&nbsp;&nbsp;Created outputs</a></h2>
<p>Several output files are created when tests are executed, and all of
them are somehow related to test results. This section discusses what
outputs are created, how to configure where they are created, and how
to fine-tune their contents.</p>
<div class="contents local topic" id="id165">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#different-output-files" id="id508">3.5.1&nbsp;&nbsp;&nbsp;Different output files</a><ul>
<li><a class="reference internal" href="#output-directory" id="id509">Output directory</a></li>
<li><a class="reference internal" href="#output-file" id="id510">Output file</a></li>
<li><a class="reference internal" href="#log-file" id="id511">Log file</a></li>
<li><a class="reference internal" href="#report-file" id="id512">Report file</a></li>
<li><a class="reference internal" href="#xunit-compatible-result-file" id="id513">XUnit compatible result file</a></li>
<li><a class="reference internal" href="#debug-file" id="id514">Debug file</a></li>
<li><a class="reference internal" href="#timestamping-output-files" id="id515">Timestamping output files</a></li>
<li><a class="reference internal" href="#setting-titles" id="id516">Setting titles</a></li>
<li><a class="reference internal" href="#setting-background-colors" id="id517">Setting background colors</a></li>
</ul>
</li>
<li><a class="reference internal" href="#log-levels" id="id518">3.5.2&nbsp;&nbsp;&nbsp;Log levels</a><ul>
<li><a class="reference internal" href="#available-log-levels" id="id519">Available log levels</a></li>
<li><a class="reference internal" href="#setting-log-level" id="id520">Setting log level</a></li>
</ul>
</li>
<li><a class="reference internal" href="#splitting-logs" id="id521">3.5.3&nbsp;&nbsp;&nbsp;Splitting logs</a></li>
<li><a class="reference internal" href="#configuring-statistics" id="id522">3.5.4&nbsp;&nbsp;&nbsp;Configuring statistics</a><ul>
<li><a class="reference internal" href="#configuring-displayed-suite-statistics" id="id523">Configuring displayed suite statistics</a></li>
<li><a class="reference internal" href="#including-and-excluding-tag-statistics" id="id524">Including and excluding tag statistics</a></li>
<li><a class="reference internal" href="#generating-combined-tag-statistics" id="id525">Generating combined tag statistics</a></li>
<li><a class="reference internal" href="#creating-links-from-tag-names" id="id526">Creating links from tag names</a></li>
<li><a class="reference internal" href="#adding-documentation-to-tags" id="id527">Adding documentation to tags</a></li>
</ul>
</li>
<li><a class="reference internal" href="#removing-keywords-from-outputs" id="id528">3.5.5&nbsp;&nbsp;&nbsp;Removing keywords from outputs</a></li>
<li><a class="reference internal" href="#setting-start-and-end-time-of-execution" id="id529">3.5.6&nbsp;&nbsp;&nbsp;Setting start and end time of execution</a></li>
<li><a class="reference internal" href="#system-log" id="id530">3.5.7&nbsp;&nbsp;&nbsp;System log</a></li>
</ul>
</div>
<div class="section" id="different-output-files">
<h3><a class="toc-backref" href="#id508">3.5.1&nbsp;&nbsp;&nbsp;Different output files</a></h3>
<p>This section explains what different output files can be created and
how to configure where they are created. Output files are configured
using command line options, which get the path to the output file in
question as an argument. A special value <span class="opt">NONE</span>
(case-insensitive) can be used to disable creating a certain output
file.</p>
<div class="section" id="output-directory">
<h4><a class="toc-backref" href="#id509">Output directory</a></h4>
<p>All output files can be set using an absolute path, in which case they
are created to the specified place, but in other cases, the path is
considered relative to the output directory. The default output
directory is the directory where the execution is started from, but it
can be altered with the <span class="opt">--outputdir (-d)</span> option. The path
set with this option is, again, relative to the execution directory,
but can naturally be given also as an absolute path. Regardless of how
a path to an individual output file is obtained, its parent directory
is created automatically, if it does not exist already.</p>
</div>
<div class="section" id="output-file">
<h4><a class="toc-backref" href="#id510">Output file</a></h4>
<p>Output files contain all the test execution results in XML
format. <a class="reference internal" href="#log-file">Log</a> and <a class="reference internal" href="#report-file">report</a> files are generated based on
output files, and output files can also be <a class="reference internal" href="#post-processing-outputs">combined and otherwise
post-processed</a> after the test execution.</p>
<p>The command line option <span class="opt">--output (-o)</span> determines the path where
the output file is created relative to the <a class="reference internal" href="#output-directory">output directory</a>. The default
name for the output file, when tests are run, is <span class="path">output.xml</span>.</p>
<p>When post-processing outputs, new output files are not created unless
<span class="opt">--output (-o)</span> option is explicitly used.</p>
<p>Starting from Robot Framework 2.6, it is possible to disable creation of
the output file also when running tests with special value <span class="opt">NONE</span>. In this
case also other output files, except for the <a class="reference internal" href="#debug-file">debug file</a>, are disabled.</p>
</div>
<div class="section" id="log-file">
<h4><a class="toc-backref" href="#id511">Log file</a></h4>
<p>Log files contain details about the executed test cases in HTML
format. They have a hierarchical structure showing test suite, test
case and keyword details. Log files are needed nearly every time when
test results are to be investigated in detail. Even though log files
also have statistics, reports are better for
getting an higher-level overview.</p>
<p>The command line option <span class="opt">--log (-l)</span> determines where log
files are created. Unless the special value <span class="opt">NONE</span> is used,
log files are always created and their default name is
<span class="path">log.html</span>.</p>
<div class="figure">
<a class="reference external image-reference" href="src/ExecutingTestCases/log_passed.html"><img alt="src/ExecutingTestCases/log_passed.png" src="src/ExecutingTestCases/log_passed.png" style="width: 500px;" /></a>
<p class="caption">An example of beginning of a log file</p>
</div>
<div class="figure">
<a class="reference external image-reference" href="src/ExecutingTestCases/log_failed.html"><img alt="src/ExecutingTestCases/log_failed.png" src="src/ExecutingTestCases/log_failed.png" style="width: 500px;" /></a>
<p class="caption">An example of a log file with keyword details visible</p>
</div>
</div>
<div class="section" id="report-file">
<h4><a class="toc-backref" href="#id512">Report file</a></h4>
<p>Report files contain an overview of the test execution results in HTML
format. They have statistics based on tags and executed test suites,
as well as a list of all executed test cases. When both reports and
logs are generated, the report has links to the log file for easy
navigation to more detailed information.  It is easy to see the
overall test execution status from report, because its background
color is green, if all <a class="reference internal" href="#setting-criticality">critical tests</a> pass, and bright red
otherwise.</p>
<p>The command line option <span class="opt">--report (-r)</span> determines where
report files are created. Similarly as log files, reports are always
created unless <span class="opt">NONE</span> is used as a value, and their default
name is <span class="path">report.html</span>.</p>
<div class="figure">
<a class="reference external image-reference" href="src/ExecutingTestCases/report_passed.html"><img alt="src/ExecutingTestCases/report_passed.png" src="src/ExecutingTestCases/report_passed.png" style="width: 500px;" /></a>
<p class="caption">An example report file of successful test execution</p>
</div>
<div class="figure">
<a class="reference external image-reference" href="src/ExecutingTestCases/report_failed.html"><img alt="src/ExecutingTestCases/report_failed.png" src="src/ExecutingTestCases/report_failed.png" style="width: 500px;" /></a>
<p class="caption">An example report file of failed test execution</p>
</div>
</div>
<div class="section" id="xunit-compatible-result-file">
<h4><a class="toc-backref" href="#id513">XUnit compatible result file</a></h4>
<p>XUnit result files contain the test run summary in XUnit compatible XML format.
This file can be used as input for tools that process XUnit data. For example,
Hudson continuous integration server has built-in support for this output format
and can be configured to generate test history based on this file.</p>
<p>XUnit output files are not created unless the command line option
<span class="opt">--xunitfile (-x)</span> is used explicitly.</p>
</div>
<div class="section" id="debug-file">
<h4><a class="toc-backref" href="#id514">Debug file</a></h4>
<p>Debug files are plain text files that are written during the test
execution. All messages got from test libraries are written to them,
as well as information about started and ended test suites, test cases
and keywords. Debug files can be used for monitoring the test
execution. This can be done using, for example, a separate <a class="reference internal" href="#file-viewing-tool">file
viewing tool</a>, or in UNIX-like systems, simply with the <span class="prog">tail
-f</span> command.</p>
<p>Debug files are not created unless the command line option
<span class="opt">--debugfile (-b)</span> is used explicitly.</p>
</div>
<div class="section" id="timestamping-output-files">
<h4><a class="toc-backref" href="#id515">Timestamping output files</a></h4>
<p>All output files listed in this section can be automatically timestamped
with the option <span class="opt">--timestampoutputs (-T)</span>. When this option is used,
a timestamp in the format <span class="opt">YYYYMMDD-hhmmss</span> is placed between
the extension and the base name of each file. The example below would,
for example, create such output files as
<span class="path">output-20080604-163225.xml</span> and <span class="path">mylog-20080604-163225.html</span>:</p>
<pre class="literal-block">
pybot --timestampoutputs --log mylog.html --report NONE tests.html
</pre>
</div>
<div class="section" id="setting-titles">
<h4><a class="toc-backref" href="#id516">Setting titles</a></h4>
<p>The default titles for <a class="reference internal" href="#log-file">logs</a> and <a class="reference internal" href="#report-file">reports</a> are generated by prefixing
the name of the top-level test suite with <span class="name">Test Log</span> or
<span class="name">Test Report</span>. Custom titles can be given from the command line
using the options <span class="opt">--logtitle</span> and <span class="opt">--reporttitle</span>,
respectively. Underscores in the given titles are converted to spaces
automatically.</p>
<p>Example:</p>
<pre class="literal-block">
pybot --logtitle Smoke_Test_Log --reporttitle Smoke_Test_Report --include smoke my_tests/
</pre>
</div>
<div class="section" id="setting-background-colors">
<h4><a class="toc-backref" href="#id517">Setting background colors</a></h4>
<p>By default the <a class="reference internal" href="#report-file">report file</a> has a green background when all the
<a class="reference internal" href="#setting-criticality">critical tests</a> pass and a red background otherwise.  These colors
can be customized by using the <span class="opt">--reportbackground</span> command line
option, which takes two or three colors separated with a colon as an
argument:</p>
<pre class="literal-block">
--reportbackground blue:red
--reportbackground green:yellow:red
--reportbackground #00E:#E00
</pre>
<p>If you specify two colors, the first one will be used instead of the
default green color and the second instead of the default red. This
allows, for example, using blue instead of green to make backgrounds
easier to separate for color blind people.</p>
<p>If you specify three colors, the first one will be used when all the
test succeed, the second when only non-critical tests have failed, and
the last when there are critical failures. This feature thus allows
using a separate background color, for example yellow, when
non-critical tests have failed.</p>
<p>The specified colors are used as a value for the <span class="code">body</span>
element's <span class="code">background</span> CSS property. The value is used as-is and
can be a HTML color name (e.g. <span class="code">red</span>), a hexadecimal value
(e.g. <span class="code">#F00</span> or <span class="code">#FF0000</span>), or an RGB value
(e.g. <span class="code">rgb(255,0,0)</span>). The default green and red colors are
specified using hexadecimal values <span class="code">#9F6</span> and <span class="code">#F33</span>,
respectively.</p>
</div>
</div>
<div class="section" id="log-levels">
<h3><a class="toc-backref" href="#id518">3.5.2&nbsp;&nbsp;&nbsp;Log levels</a></h3>
<div class="section" id="available-log-levels">
<h4><a class="toc-backref" href="#id519">Available log levels</a></h4>
<p>Messages in <a class="reference internal" href="#log-file">log files</a> can have different log levels. Some of the
messages are written by Robot Framework itself, but also executed
keywords can <a class="reference internal" href="#logging-information">log information</a> using different levels. The available
log levels are:</p>
<dl class="docutils">
<dt><span class="msg">FAIL</span></dt>
<dd>Used when a keyword fails. Can be used only by Robot Framework itself.</dd>
<dt><span class="msg">WARN</span></dt>
<dd>Used to display warnings. They shown also in <a class="reference internal" href="#errors-and-warnings-during-execution">the console and in
the Test Execution Errors section in log files</a>, but they
do not affect the test case status.</dd>
<dt><span class="msg">INFO</span></dt>
<dd>The default level for normal messages. By default,
messages below this level are not shown in the log file.</dd>
<dt><span class="msg">DEBUG</span></dt>
<dd>Used for debugging purposes. Useful, for example, for
logging what libraries are doing internally. When a keyword fails,
a traceback showing where in the code the failure occurred is
logged using this level automatically.</dd>
<dt><span class="msg">TRACE</span></dt>
<dd>More detailed debugging level. The keyword arguments and return values
are automatically logged using this level.</dd>
</dl>
</div>
<div class="section" id="setting-log-level">
<h4><a class="toc-backref" href="#id520">Setting log level</a></h4>
<p>By default, log messages below the <span class="msg">INFO</span> level are not logged, but this
threshold can be changed from the command line using the
<span class="opt">--loglevel (-L)</span> option. This option takes any of the
available log levels as an argument, and that level becomes the new
threshold level. A special value <span class="msg">NONE</span> can also be used to
disable logging altogether.</p>
<p>Starting from Robot Framework 2.5.2, it is possible to use the
<span class="opt">--loglevel</span> option also when <a class="reference internal" href="#post-processing-outputs">post-processing outputs</a> with
<span class="prog">rebot</span>. This allows, for example, running tests initially with
the <span class="msg">TRACE</span> level, and generating smaller log files for normal
viewing later with the <span class="msg">INFO</span> level. By default all the messages
included during execution will be included also with <span class="prog">rebot</span>.
Messages ignored during the execution cannot be recovered.</p>
<p>Another possibility to change the log level is using the <a class="reference internal" href="#builtin-library">BuiltIn
keyword</a> <span class="name">Set Log Level</span> in the test data. It takes the same
arguments as the <span class="opt">--loglevel</span> option, and it also returns the
old level so that it can be restored later, for example, in a <a class="reference internal" href="#test-setup-and-teardown">test
teardown</a>.</p>
</div>
</div>
<div class="section" id="splitting-logs">
<h3><a class="toc-backref" href="#id521">3.5.3&nbsp;&nbsp;&nbsp;Splitting logs</a></h3>
<p>Normally the log file is just a single HTML file. When the amount of he test
cases increases, the size of the file can grow so large that opening it into
a browser is inconvenient or even impossible. Starting from Robot Framework
2.6, it is possible to use the <span class="opt">--splitlog</span> option to split parts of
the log into external files that are loaded transparently into the browser
when needed.</p>
<p>The main benefit of splitting logs is that individual log parts are so small
that opening and browsing the log file is possible even if the amount
of the test data is very large. A small drawback is that the overall size taken
by the log file increases.</p>
<p>Technically the test data related to each test case is saved into
a JavaScript file in the same folder as the main log file. These files have
names such as <span class="path">log-42.js</span> where <span class="path">log</span> is the base name of the
main log file and <span class="path">42</span> is an incremented index.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">When copying the log files, you need to copy also all the
<span class="path">log-*.js</span> files or some information will be missing.</p>
</div>
</div>
<div class="section" id="configuring-statistics">
<h3><a class="toc-backref" href="#id522">3.5.4&nbsp;&nbsp;&nbsp;Configuring statistics</a></h3>
<p>There are several command line options that can be used to configure
and adjust the contents of the <span class="name">Statistics by Tag</span>, <span class="name">Statistics
by Suite</span> and <span class="name">Test Details by Tag</span> tables in different output
files. All these options work both when executing test cases and when
post-processing outputs.</p>
<div class="section" id="configuring-displayed-suite-statistics">
<h4><a class="toc-backref" href="#id523">Configuring displayed suite statistics</a></h4>
<p>When a deeper suite structure is executed, showing all the test suite
levels in the <span class="name">Statistics by Suite</span> table may make the table
somewhat difficult to read. Bt default all suites are shown, but you can
control this with the command line option <span class="opt">--suitestatlevel</span> which
takes the level of suites to show as an argument:</p>
<pre class="literal-block">
--suitestatlevel 3
</pre>
</div>
<div class="section" id="including-and-excluding-tag-statistics">
<h4><a class="toc-backref" href="#id524">Including and excluding tag statistics</a></h4>
<p>When many tags are used, the <span class="name">Statistics by Tag</span> table can become
quite congested. If this happens, the command line options
<span class="opt">--tagstatinclude</span> and <span class="opt">--tagstatexclude</span> can be
used to select which tags to display, similarly as
<span class="opt">--include</span> and <span class="opt">--exclude</span> are used to <a class="reference internal" href="#by-tag-names">select test
cases</a>:</p>
<pre class="literal-block">
--tagstatinclude some-tag --tagstatinclude another-tag
--tagstatexclude owner-*
--tagstatinclude prefix-* --tagstatexclude prefix-13
</pre>
</div>
<div class="section" id="generating-combined-tag-statistics">
<h4><a class="toc-backref" href="#id525">Generating combined tag statistics</a></h4>
<p>The command line option <span class="opt">--tagstatcombine</span> can be used to
generate aggregate tags that combine statistics from multiple
tags. There are three somewhat different ways for giving arguments for
this option:</p>
<dl class="docutils">
<dt>One tag as a <a class="reference internal" href="#option-value-as-simple-pattern">simple pattern</a></dt>
<dd>All tags matching the given pattern are combined together.</dd>
<dt>Two or more tags separated by <span class="code">AND</span> or <span class="code">&amp;</span></dt>
<dd>The combined statistics contain tests that have all the listed tags.
Tags can be given as simple patterns.</dd>
<dt>Two or more tags separated by <span class="code">NOT</span></dt>
<dd>The combined statistics contain tests that have the first tag but
not the others. Also in this case tags may be patterns.</dd>
</dl>
<p>The following examples illustrate these usages, and the figure below shows a snippet
of the resulting <span class="name">Statistics by Tag</span> table when the example test data is
executed with these options:</p>
<pre class="literal-block">
--tagstatcombine owner-*
--tagstatcombine smokeANDmytag
--tagstatcombine smokeNOTowner-janne*
</pre>
<div class="figure">
<img alt="src/ExecutingTestCases/tagstatcombine.png" src="src/ExecutingTestCases/tagstatcombine.png" style="width: 550px;" />
<p class="caption">Examples of combined tag statistics</p>
</div>
<p>As the above example shows, the name of the added combined statistic
is, by default, generated from the given pattern. In certain
situations this name can look pretty cryptic and it is possible to
specify a more descriptive name. This name is given after the pattern
separating it with a colon (<span class="code">:</span>). Example below generates
combined tag so that the name shown in reports and logs is
<span class="name">Critical Tests</span>:</p>
<pre class="literal-block">
--tagstatcombine *NOTnon-critical:Critical_Tests
</pre>
</div>
<div class="section" id="creating-links-from-tag-names">
<h4><a class="toc-backref" href="#id526">Creating links from tag names</a></h4>
<p>You can add external links to the <span class="name">Statistics by Tag</span> table by
using the command line option <span class="opt">--tagstatlink</span>. Arguments to this
option are given in the format <span class="opt">tag:link:name</span>, where <span class="opt">tag</span>
specifies the tags to assign the link to, <span class="opt">link</span> is the link to
be created, and <span class="opt">name</span> is the name to give to the link.</p>
<p><span class="opt">tag</span> may be a single tag, but more commonly a <a class="reference internal" href="#option-value-as-simple-pattern">simple pattern</a>
where <span class="code">*</span> matches anything and <span class="code">?</span> matches any single
character. When <span class="opt">tag</span> is a pattern, the matches to wildcards may
be used in <span class="opt">link</span> and <span class="opt">title</span> with the syntax <span class="code">%N</span>,
where &quot;N&quot; is the index of the match starting from 1.</p>
<p>The following examples illustrate the usage of this option, and the
figure below shows a snippet of the resulting <span class="name">Statistics by
Tag</span> table when example test data is executed with these options:</p>
<pre class="literal-block">
--tagstatlink mytag:http://www.google.com:Google
--tagstatlink jython-bug-*:http://bugs.jython.org/issue_%1:Jython-bugs
--tagstatlink owner-*:mailto:%1&#64;domain.com?subject=Acceptance_Tests:Send_Mail
</pre>
<div class="figure">
<img alt="src/ExecutingTestCases/tagstatlink.png" src="src/ExecutingTestCases/tagstatlink.png" style="width: 550px;" />
<p class="caption">Examples of links from tag names</p>
</div>
</div>
<div class="section" id="adding-documentation-to-tags">
<h4><a class="toc-backref" href="#id527">Adding documentation to tags</a></h4>
<p>Tags can be given a documentation with the command line option
<span class="opt">--tagdoc</span>, which takes an argument in the format
<span class="opt">tag:doc</span>. <span class="opt">tag</span> is the name of the tag to assign the
documentation to, and it can also be a <a class="reference internal" href="#option-value-as-simple-pattern">simple pattern</a> matching
multiple tags. <span class="opt">doc</span> is the assigned documentation. Underscores
in the documentation are automatically converted to spaces and it
can also contain <a class="reference internal" href="#documentation-formatting">HTML formatting</a>.</p>
<p>The given documentation is shown with matching tags in the <span class="name">Test
Details by Tag</span> table, and as a tool tip for these tags in the
<span class="name">Statistics by Tag</span> table. If one tag gets multiple documentations,
they are combined together and separated with an ampersand.</p>
<p>Examples:</p>
<pre class="literal-block">
--tagdoc mytag:My_documentation
--tagdoc regression:*See*_http://info.html
--tagdoc owner-*:Original_author
</pre>
</div>
</div>
<div class="section" id="removing-keywords-from-outputs">
<h3><a class="toc-backref" href="#id528">3.5.5&nbsp;&nbsp;&nbsp;Removing keywords from outputs</a></h3>
<p>Most of the content of <a class="reference internal" href="#output-file">output files</a> comes from keywords and especially their
log messages. When creating higher level reports, log files are not necessarily
needed at all, and then keywords and their messages just take space
unnecessarily. Log files themselves can also grow overly large if they contain
<a class="reference internal" href="#for-loops">for loops</a> or other constructs that repeat certain keywords multiple times.</p>
<p>In these situations, the command line option <span class="opt">--removekeywords</span> can be
used to dispose of unnecessary keywords. It can be used both when executing
tests and with <span class="prog">rebot</span>, but in the former case keywords are not removed
from the output file. Keywords that contain warnings are not removed except
in <span class="opt">ALL</span> mode.</p>
<p>The option has the following modes of operation:</p>
<dl class="docutils">
<dt><span class="opt">ALL</span></dt>
<dd>Remove data from all keywords unconditionally.</dd>
<dt><span class="opt">PASSED</span></dt>
<dd>Remove keyword data from test cases that have passed and do not
contain <a class="reference internal" href="#warnings">warnings</a>. In most cases, log files created after this contain
enough information to investigate possible failures.</dd>
<dt><span class="opt">FOR</span></dt>
<dd>Remove all passed iterations from <a class="reference internal" href="#for-loops">for loops</a>.</dd>
<dt><span class="opt">WUKS</span></dt>
<dd>Remove all but last failing keyword inside <a class="reference internal" href="#builtin-library">BuiltIn</a> keyword
<span class="name">Wait Until Keyword Succeeds</span>.</dd>
</dl>
<p>Examples:</p>
<pre class="literal-block">
rebot --removekeywords all output.xml
pybot --removekeywords passed --removekeywords for tests.txt
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The support for using <span class="opt">--removekeywords</span> when executing tests as well
as <span class="opt">FOR</span> and <span class="opt">WUKS</span> modes were added in Robot Framework 2.7.</p>
</div>
</div>
<div class="section" id="setting-start-and-end-time-of-execution">
<h3><a class="toc-backref" href="#id529">3.5.6&nbsp;&nbsp;&nbsp;Setting start and end time of execution</a></h3>
<p>When <a class="reference internal" href="#combining-outputs">combining outputs</a> using <span class="prog">rebot</span>, it is possible to set the start
and end time of the combined test suite using the options <span class="opt">--starttime</span>
and <span class="opt">--endtime</span>, respectively. This is convenient, because by default,
combined suites do not have these values. When both the start and end time are
given, the elapsed time is also calculated based on them. Otherwise the elapsed
time is got by adding the elapsed times of the child test suites together.</p>
<p>Starting from Robot Framework 2.5.6, it is also possible to use the above
mentioned options to set start and end times for a single suite when using
<span class="prog">rebot</span>.  Using these options with a single output always affects the
elapsed time of the suite.</p>
<p>Times must be given as timestamps in the format <span class="code">YYYY-MM-DD
hh:mm:ss.mil</span>, where all separators are optional and the parts from
milliseconds to hours can be omitted. For example, <span class="code">2008-06-11
17:59:20.495</span> is equivalent both to <span class="code">20080611-175920.495</span> and
<span class="code">20080611175920495</span>, and also mere <span class="code">20080611</span> would work.</p>
<p>Examples:</p>
<pre class="literal-block">
rebot --starttime 20080611-17:59:20.495 output1.xml output2.xml
rebot --starttime 20080611-175920 --endtime 20080611-180242 *.xml
rebot --starttime 20110302-1317 --endtime 20110302-11418 myoutput.xml
</pre>
</div>
<div class="section" id="system-log">
<h3><a class="toc-backref" href="#id530">3.5.7&nbsp;&nbsp;&nbsp;System log</a></h3>
<p>Robot Framework has its own plain-text system log where it writes
information about</p>
<blockquote>
<ul class="simple">
<li>Processed and skipped test data files</li>
<li>Imported test libraries, resource files and variable files</li>
<li>Executed test suites and test cases</li>
<li>Created outputs</li>
</ul>
</blockquote>
<p>Normally users never need this information, but it can be
useful when investigating problems with test libraries or Robot Framework
itself. A system log is not created by default, but it can be enabled
by setting the environment variable <span class="opt">ROBOT_SYSLOG_FILE</span> so
that it contains a path to the selected file.</p>
<p>A system log has the same <a class="reference internal" href="#log-levels">log levels</a> as a normal log file, with the
exception that instead of <span class="msg">FAIL</span> it has the <span class="msg">ERROR</span>
level. The threshold level to use can be altered using the
<span class="opt">ROBOT_SYSLOG_LEVEL</span> environment variable like shown in the
example below.  Possible <a class="reference internal" href="#errors-and-warnings-during-execution">unexpected errors and warnings</a> are
written into the system log in addition to the console and the normal
log file.</p>
<div class="highlight"><pre><span class="c">#!/bin/bash</span>

<span class="nb">export </span><span class="nv">ROBOT_SYSLOG_FILE</span><span class="o">=</span>/tmp/syslog.txt
<span class="nb">export </span><span class="nv">ROBOT_SYSLOG_LEVEL</span><span class="o">=</span>DEBUG

pybot --name Syslog_example path/to/tests
</pre></div>
</div>
</div>
</div>
<div class="section" id="extending-robot-framework">
<h1><a class="toc-backref" href="#id276">4&nbsp;&nbsp;&nbsp;Extending Robot Framework</a></h1>
<div class="contents local topic" id="id171">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#creating-test-libraries" id="id531">4.1&nbsp;&nbsp;&nbsp;Creating test libraries</a></li>
<li><a class="reference internal" href="#remote-library-interface" id="id532">4.2&nbsp;&nbsp;&nbsp;Remote library interface</a></li>
<li><a class="reference internal" href="#using-listener-interface" id="id533">4.3&nbsp;&nbsp;&nbsp;Using listener interface</a></li>
<li><a class="reference internal" href="#using-internal-apis" id="id534">4.4&nbsp;&nbsp;&nbsp;Using internal APIs</a></li>
<li><a class="reference internal" href="#using-robot-framework-from-java" id="id535">4.5&nbsp;&nbsp;&nbsp;Using Robot Framework from Java</a></li>
</ul>
</div>
<div class="section" id="creating-test-libraries">
<h2><a class="toc-backref" href="#id531">4.1&nbsp;&nbsp;&nbsp;Creating test libraries</a></h2>
<p>Robot Framework's actual testing capabilities are provided by test
libraries. There are many existing libraries, some of which are even
bundled with the core framework, but there is still often a need to
create new ones. This task is not too complicated because, as this
chapter illustrates, Robot Framework's library API is simple
and straightforward.</p>
<div class="contents local topic" id="id172">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#id173" id="id536">4.1.1&nbsp;&nbsp;&nbsp;Introduction</a><ul>
<li><a class="reference internal" href="#supported-programming-languages" id="id537">Supported programming languages</a></li>
<li><a class="reference internal" href="#different-test-library-apis" id="id538">Different test library APIs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#creating-test-library-class-or-module" id="id539">4.1.2&nbsp;&nbsp;&nbsp;Creating test library class or module</a><ul>
<li><a class="reference internal" href="#test-library-names" id="id540">Test library names</a></li>
<li><a class="reference internal" href="#providing-arguments-to-test-libraries" id="id541">Providing arguments to test libraries</a></li>
<li><a class="reference internal" href="#test-library-scope" id="id542">Test library scope</a></li>
<li><a class="reference internal" href="#specifying-library-version" id="id543">Specifying library version</a></li>
</ul>
</li>
<li><a class="reference internal" href="#creating-static-keywords" id="id544">4.1.3&nbsp;&nbsp;&nbsp;Creating static keywords</a><ul>
<li><a class="reference internal" href="#what-methods-are-considered-keywords" id="id545">What methods are considered keywords</a></li>
<li><a class="reference internal" href="#keyword-names" id="id546">Keyword names</a></li>
<li><a class="reference internal" href="#keyword-arguments" id="id547">Keyword arguments</a></li>
<li><a class="reference internal" href="#default-values-to-keywords" id="id548">Default values to keywords</a></li>
<li><a class="reference internal" href="#id181" id="id549">Variable number of arguments</a></li>
<li><a class="reference internal" href="#argument-types" id="id550">Argument types</a></li>
</ul>
</li>
<li><a class="reference internal" href="#communicating-with-robot-framework" id="id551">4.1.4&nbsp;&nbsp;&nbsp;Communicating with Robot Framework</a><ul>
<li><a class="reference internal" href="#reporting-keyword-status" id="id552">Reporting keyword status</a></li>
<li><a class="reference internal" href="#stopping-test-execution" id="id553">Stopping test execution</a></li>
<li><a class="reference internal" href="#continuing-test-execution-despite-of-failures" id="id554">Continuing test execution despite of failures</a></li>
<li><a class="reference internal" href="#logging-information" id="id555">Logging information</a></li>
<li><a class="reference internal" href="#programmatic-logging-apis" id="id556">Programmatic logging APIs</a></li>
<li><a class="reference internal" href="#logging-during-library-initialization" id="id557">Logging during library initialization</a></li>
<li><a class="reference internal" href="#returning-values" id="id558">Returning values</a></li>
<li><a class="reference internal" href="#communication-when-using-threads" id="id559">Communication when using threads</a></li>
</ul>
</li>
<li><a class="reference internal" href="#distributing-test-libraries" id="id560">4.1.5&nbsp;&nbsp;&nbsp;Distributing test libraries</a><ul>
<li><a class="reference internal" href="#documenting-libraries" id="id561">Documenting libraries</a></li>
<li><a class="reference internal" href="#testing-libraries" id="id562">Testing libraries</a></li>
<li><a class="reference internal" href="#packaging-libraries" id="id563">Packaging libraries</a></li>
<li><a class="reference internal" href="#deprecating-keywords" id="id564">Deprecating keywords</a></li>
</ul>
</li>
<li><a class="reference internal" href="#dynamic-library-api" id="id565">4.1.6&nbsp;&nbsp;&nbsp;Dynamic library API</a><ul>
<li><a class="reference internal" href="#getting-keyword-names" id="id566">Getting keyword names</a></li>
<li><a class="reference internal" href="#running-keywords" id="id567">Running keywords</a></li>
<li><a class="reference internal" href="#getting-keyword-arguments" id="id568">Getting keyword arguments</a></li>
<li><a class="reference internal" href="#getting-keyword-documentation" id="id569">Getting keyword documentation</a></li>
<li><a class="reference internal" href="#getting-general-library-documentation" id="id570">Getting general library documentation</a></li>
<li><a class="reference internal" href="#summary" id="id571">Summary</a></li>
</ul>
</li>
<li><a class="reference internal" href="#hybrid-library-api" id="id572">4.1.7&nbsp;&nbsp;&nbsp;Hybrid library API</a><ul>
<li><a class="reference internal" href="#id199" id="id573">Getting keyword names</a></li>
<li><a class="reference internal" href="#id200" id="id574">Running keywords</a></li>
<li><a class="reference internal" href="#getting-keyword-arguments-and-documentation" id="id575">Getting keyword arguments and documentation</a></li>
<li><a class="reference internal" href="#id202" id="id576">Summary</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-robot-framework-s-internal-modules" id="id577">4.1.8&nbsp;&nbsp;&nbsp;Using Robot Framework's internal modules</a></li>
<li><a class="reference internal" href="#extending-existing-test-libraries" id="id578">4.1.9&nbsp;&nbsp;&nbsp;Extending existing test libraries</a><ul>
<li><a class="reference internal" href="#modifying-original-source-code" id="id579">Modifying original source code</a></li>
<li><a class="reference internal" href="#using-inheritance" id="id580">Using inheritance</a></li>
<li><a class="reference internal" href="#using-other-libraries-directly" id="id581">Using other libraries directly</a></li>
<li><a class="reference internal" href="#getting-active-library-instance-from-robot-framework" id="id582">Getting active library instance from Robot Framework</a></li>
<li><a class="reference internal" href="#libraries-using-dynamic-or-hybrid-api" id="id583">Libraries using dynamic or hybrid API</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="id173">
<h3><a class="toc-backref" href="#id536">4.1.1&nbsp;&nbsp;&nbsp;Introduction</a></h3>
<div class="section" id="supported-programming-languages">
<h4><a class="toc-backref" href="#id537">Supported programming languages</a></h4>
<p>Robot Framework itself is written with <a class="reference external" href="http://www.python.org/">Python</a> and naturally test
libraries extending it can be implemented using the same
language. When running the framework on <a class="reference external" href="http://www.jython.org/">Jython</a>, libraries can also be
implemented using <a class="reference external" href="http://java.sun.com/">Java</a>. Pure Python code works both on Python and
Jython, assuming that it does not use syntax or modules that are not
available on Jython. When using Python, it is also possible to
implement libraries with C using <a class="reference external" href="http://docs.python.org/c-api/index.html">Python C API</a>, although it is
often easier to interact with C code from Python libraries using
<a class="reference external" href="http://docs.python.org/library/ctypes.html">ctypes</a> module.</p>
<p>Libraries implemented using these natively supported languages can
also act as wrappers to functionality implemented using other
programming languages. A good example of this approach is the <a class="reference internal" href="#remote-library">Remote
library</a>, and another widely used approaches is running external
scripts or tools as separate processes.</p>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p class="last"><a class="reference external" href="http://code.google.com/p/robotframework/wiki/PythonTutorial">Python Tutorial for Robot Framework Test Library Developers</a>
covers enough of Python language to get started writing test
libraries using it. It also contains a simple example library
and test cases that you can execute and otherwise investigate
on your machine.</p>
</div>
</div>
<div class="section" id="different-test-library-apis">
<h4><a class="toc-backref" href="#id538">Different test library APIs</a></h4>
<p>Robot Framework has three different test library APIs.</p>
<p>Static API</p>
<blockquote>
The simplest approach is having a module (in Python) or a class
(in Python or Java) with methods which map directly to
<a class="reference internal" href="#keyword-names">keyword names</a>. Keywords also take the same <a class="reference internal" href="#keyword-arguments">arguments</a> as
the methods implementing them.  Keywords <a class="reference internal" href="#reporting-keyword-status">report failures</a> with
exceptions, <a class="reference internal" href="#logging-information">log</a> by writing to standard output and can <a class="reference internal" href="#returning-values">return
values</a> using the <span class="code">return</span> statement.</blockquote>
<p>Dynamic API</p>
<blockquote>
Dynamic libraries are classes that implement a method to get the names
of the keywords they implement, and another method to execute a named
keyword with given arguments. The names of the keywords to implement, as
well as how they are executed, can be determined dynamically at
runtime, but reporting the status, logging and returning values is done
similarly as in the static API.</blockquote>
<p>Hybrid API</p>
<blockquote>
This is a hybrid between the static and the dynamic API. Libraries are
classes with a method telling what keywords they implement, but
those keywords must be available directly. Everything else except
discovering what keywords are implemented is similar as in the
static API.</blockquote>
<p>All these APIs are described in this chapter. Everything is based on
how the static API works, so its functions are discussed first. How
the <a class="reference internal" href="#dynamic-library-api">dynamic library API</a> and the <a class="reference internal" href="#hybrid-library-api">hybrid library API</a> differ from it
is then discussed in sections of their own.</p>
<p>The examples in this chapter are mainly about using Python, but they
should be easy to understand also for Java-only developers. In those
few cases where APIs have differences, both usages are explained with
adequate examples.</p>
</div>
</div>
<div class="section" id="creating-test-library-class-or-module">
<h3><a class="toc-backref" href="#id539">4.1.2&nbsp;&nbsp;&nbsp;Creating test library class or module</a></h3>
<p>Test libraries can be implemented as Python modules and Python or Java
classes.</p>
<div class="section" id="test-library-names">
<h4><a class="toc-backref" href="#id540">Test library names</a></h4>
<p>The name of a test library that is used when a library is imported is
the same as the name of the module or class implementing it. For
example, if you have a Python module <span class="code">MyLibrary</span> (that is, the
file <span class="path">MyLibrary.py</span>), it will create a library with a name
<span class="name">MyLibrary</span>. Similarly, a Java class <span class="code">YourLibrary</span>, when
it is not in any package, creates a library with exactly that name.</p>
<p>Python classes are always inside a module. If the name of a class
implementing a library is the same as the name of the module, Robot
Framework allows dropping the module name when importing the
library. For example, the class <span class="code">MyLib</span> in the <span class="path">MyLib.py</span>
file can be used as a library with the name <span class="name">MyLib</span>. If the
module name and class name are different, libraries must be taken into
use using both module and class names, such as
<span class="name">mymodule.MyLibrary</span>.</p>
<p>Java classes in a non-default package must be taken into use with the
full name. For example, the class <span class="code">MyLib</span> in the
<span class="code">com.mycompany.myproject</span> package must be imported with the name
<span class="name">com.mycompany.myproject.MyLib</span>.</p>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p class="last">If the library name is really long, for example when the Java
package name is long, it is recommended to give the library a
simpler alias by using the <a class="reference internal" href="#setting-custom-name-to-test-library">WITH NAME syntax</a>.</p>
</div>
</div>
<div class="section" id="providing-arguments-to-test-libraries">
<h4><a class="toc-backref" href="#id541">Providing arguments to test libraries</a></h4>
<p>All test libraries implemented as classes can take arguments. These
arguments are specified in the Setting table after the library name,
and when Robot Framework creates an instance of the imported library,
it passes them to its constructor. Libraries implemented as a module
cannot take any arguments, so trying to use those results in an error.</p>
<p>The number of arguments needed by the library is the same
as the number of arguments accepted by the library's
constructor. The default values and variable number of arguments work
similarly as with <a class="reference internal" href="#keyword-arguments">keyword arguments</a>, with the exception that there
is no variable argument support for Java libraries. Arguments passed
to the library, as well as the library name itself, can be specified
using variables, so it is possible to alter them, for example, from the
command line.</p>
<table border="1" class="example docutils">
<caption>Importing a test library with arguments</caption>
<colgroup>
<col width="25%" />
<col width="31%" />
<col width="25%" />
<col width="19%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>MyLibrary</td>
<td>10.0.0.1</td>
<td>8080</td>
</tr>
<tr><td>Library</td>
<td>AnotherLib</td>
<td>${VAR}</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>Example implementations, first one in Python and second in Java, for
the libraries used in the above example:</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">example</span> <span class="kn">import</span> <span class="n">Connection</span>

<span class="k">class</span> <span class="nc">MyLibrary</span><span class="p">:</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">host</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">80</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_conn</span> <span class="o">=</span> <span class="n">Connection</span><span class="p">(</span><span class="n">host</span><span class="p">,</span> <span class="nb">int</span><span class="p">(</span><span class="n">port</span><span class="p">))</span>

    <span class="k">def</span> <span class="nf">send_message</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_conn</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
</pre></div>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">AnotherLib</span> <span class="o">{</span>

    <span class="kd">private</span> <span class="n">String</span> <span class="n">setting</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span>

    <span class="kd">public</span> <span class="nf">AnotherLib</span><span class="o">(</span><span class="n">String</span> <span class="n">setting</span><span class="o">)</span> <span class="o">{</span>
        <span class="n">setting</span> <span class="o">=</span> <span class="n">setting</span><span class="o">;</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">doSomething</span><span class="o">()</span> <span class="o">{</span>
        <span class="k">if</span> <span class="n">setting</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="s">&quot;42&quot;</span><span class="o">)</span> <span class="o">{</span>
            <span class="c1">// do something ...</span>
        <span class="o">}</span>
    <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<div class="section" id="test-library-scope">
<h4><a class="toc-backref" href="#id542">Test library scope</a></h4>
<p>Libraries implemented as classes can have an internal state, which can
be altered by keywords and with arguments to the constructor of the
library. Because the state can affect how keywords actually behave, it
is important to make sure that changes in one test case do not
accidentally affect other test cases. These kind of dependencies may
create hard-to-debug problems, for example, when new test cases are
added and they use the library inconsistently.</p>
<p>Robot Framework attempts to keep test cases independent from each
other: by default, it creates new instances of test libraries for
every test case. However, this behavior is not always desirable,
because sometimes test cases should be able to share a common
state. Additionally, all libraries do not have a state and creating
new instances of them is simply not needed.</p>
<p>Test libraries can control when new libraries are created with a
class attribute <span class="code">ROBOT_LIBRARY_SCOPE</span> . This attribute must be
a string and it can have the following three values:</p>
<dl class="docutils">
<dt><span class="code">TEST CASE</span></dt>
<dd>A new instance is created for every test case. A possible suite setup
and suite teardown share yet another instance. This is the default.</dd>
<dt><span class="code">TEST SUITE</span></dt>
<dd>A new instance is created for every test suite. The lowest-level test
suites, created from test case files and containing test cases, have
instances of their own, and higher-level suites all get their own instances
for their possible setups and teardowns.</dd>
<dt><span class="code">GLOBAL</span></dt>
<dd>Only one instance is created during the whole test execution and it
is shared by all test cases and test suites. Libraries created from
modules are always global.</dd>
</dl>
<p>When the <span class="code">TEST SUITE</span> or <span class="code">GLOBAL</span> scopes are used with test
libraries that have a state, it is recommended that libraries have some
special keyword for cleaning up the state. This keyword can then be
used, for example, in a suite setup or teardown to ensure that test
cases in the next test suites can start from a known state. For example,
<span class="name">SeleniumLibrary</span> uses the <span class="code">GLOBAL</span> scope to enable
using the same browser in different test cases without having to
reopen it, and it also has the <span class="name">Close All Browsers</span> keyword for
easily closing all open browsers.</p>
<p>Example Python library using the <span class="code">TEST SUITE</span> scope:</p>
<div class="highlight"><pre><span class="k">class</span> <span class="nc">ExampleLibrary</span><span class="p">:</span>

    <span class="n">ROBOT_LIBRARY_SCOPE</span> <span class="o">=</span> <span class="s">&#39;TEST SUITE&#39;</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_counter</span> <span class="o">=</span> <span class="mi">0</span>

    <span class="k">def</span> <span class="nf">count</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_counter</span> <span class="o">+=</span> <span class="mi">1</span>
        <span class="k">print</span> <span class="bp">self</span><span class="o">.</span><span class="n">_counter</span>

    <span class="k">def</span> <span class="nf">clear_counter</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_counter</span> <span class="o">=</span> <span class="mi">0</span>
</pre></div>
<p>Example Java library using the <span class="code">GLOBAL</span> scope:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">ExampleLibrary</span> <span class="o">{</span>

    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="n">String</span> <span class="n">ROBOT_LIBRARY_SCOPE</span> <span class="o">=</span> <span class="s">&quot;GLOBAL&quot;</span><span class="o">;</span>

    <span class="kd">private</span> <span class="kt">int</span> <span class="n">counter</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">count</span><span class="o">()</span> <span class="o">{</span>
        <span class="n">counter</span> <span class="o">+=</span> <span class="mi">1</span><span class="o">;</span>
        <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">counter</span><span class="o">);</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">clearCounter</span><span class="o">()</span> <span class="o">{</span>
        <span class="n">counter</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span>
    <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<div class="section" id="specifying-library-version">
<h4><a class="toc-backref" href="#id543">Specifying library version</a></h4>
<p>When a test library is taken into use, Robot Framework tries to
determine its version. This information is then written into the <a class="reference internal" href="#system-log">syslog</a>
to provide debugging information. Library documentation tool
<a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> also writes this information into the keyword
documentations it generates.</p>
<p>Version information is read from attribute
<span class="code">ROBOT_LIBRARY_VERSION</span>, similarly as <a class="reference internal" href="#test-library-scope">test library scope</a> is
read from <span class="code">ROBOT_LIBRARY_SCOPE</span>. If
<span class="code">ROBOT_LIBRARY_VERSION</span> does not exist, information is tried to
be read from <span class="code">__version__</span> attribute. These attributes must be
class or module attributes, depending whether the library is
implemented as a class or a module.  For Java libraries the version
attribute must be declared as <span class="code">static final</span>.</p>
<p>An example Python module using <span class="code">__version__</span>:</p>
<div class="highlight"><pre><span class="n">__version__</span> <span class="o">=</span> <span class="s">&#39;0.1&#39;</span>

<span class="k">def</span> <span class="nf">keyword</span><span class="p">():</span>
    <span class="k">pass</span>
</pre></div>
<p>A Java class using <span class="code">ROBOT_LIBRARY_VERSION</span>:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">VersionExample</span> <span class="o">{</span>

    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="n">String</span> <span class="n">ROBOT_LIBRARY_VERSION</span> <span class="o">=</span> <span class="s">&quot;1.0.2&quot;</span><span class="o">;</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">keyword</span><span class="o">()</span> <span class="o">{</span>
    <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="creating-static-keywords">
<h3><a class="toc-backref" href="#id544">4.1.3&nbsp;&nbsp;&nbsp;Creating static keywords</a></h3>
<div class="section" id="what-methods-are-considered-keywords">
<h4><a class="toc-backref" href="#id545">What methods are considered keywords</a></h4>
<p>When the static library API is used, Robot Framework uses reflection
to find out what public methods the library class or module
implements. It will exclude all methods starting with an underscore,
and with Java libraries also methods that are implemented only in
<span class="code">java.lang.Object</span> are ignored. All the methods that are not
ignored are considered keywords. For example, the Python and Java
libraries below implement single keyword <span class="name">My Keyword</span>.</p>
<div class="highlight"><pre><span class="k">class</span> <span class="nc">MyLibrary</span><span class="p">:</span>

    <span class="k">def</span> <span class="nf">my_keyword</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_helper_method</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">_helper_method</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">arg</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>
</pre></div>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyLibrary</span> <span class="o">{</span>

    <span class="kd">public</span> <span class="n">String</span> <span class="nf">myKeyword</span><span class="o">(</span><span class="n">String</span> <span class="n">arg</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">return</span> <span class="nf">helperMethod</span><span class="o">(</span><span class="n">arg</span><span class="o">);</span>
    <span class="o">}</span>

    <span class="kd">private</span> <span class="n">String</span> <span class="nf">helperMethod</span><span class="o">(</span><span class="n">String</span> <span class="n">arg</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">return</span> <span class="n">arg</span><span class="o">.</span><span class="na">toUpperCase</span><span class="o">();</span>
    <span class="o">}</span>
<span class="o">}</span>
</pre></div>
<p>When the library is implemented as a Python module, it is also
possible to limit what methods are keywords by using Python's
<span class="code">__all__</span> attribute. If <span class="code">__all__</span> is used, only methods
listed in it can be keywords. For example, the library below
implements keywords <span class="name">Example Keyword</span> and <span class="name">Second
Example</span>. Without <span class="code">__all__</span>, it would implement also keywords
<span class="name">Not Exposed As Keyword</span> and <span class="name">Current Thread</span>. The most
important usage for <span class="code">__all__</span> is making sure imported helper
methods, such as <span class="code">current_thread</span> in the example below, are not
accidentally exposed as keywords.</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">threading</span> <span class="kn">import</span> <span class="n">current_thread</span>

<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s">&#39;example_keyword&#39;</span><span class="p">,</span> <span class="s">&#39;second_example&#39;</span><span class="p">]</span>

<span class="k">def</span> <span class="nf">example_keyword</span><span class="p">():</span>
    <span class="k">if</span> <span class="n">current_thread</span><span class="p">()</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">&#39;MainThread&#39;</span><span class="p">:</span>
        <span class="k">print</span> <span class="s">&#39;Running in main thread&#39;</span>

<span class="k">def</span> <span class="nf">second_example</span><span class="p">():</span>
    <span class="k">pass</span>

<span class="k">def</span> <span class="nf">not_exposed_as_keyword</span><span class="p">():</span>
    <span class="k">pass</span>
</pre></div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Support for the <span class="code">__all__</span> attribute is available from
Robot Framework 2.5.5 onwards.</p>
</div>
</div>
<div class="section" id="keyword-names">
<h4><a class="toc-backref" href="#id546">Keyword names</a></h4>
<p>Keyword names used in the test data are compared with method names to
find the method implementing these keywords. Name comparison is
case-insensitive, and also spaces and underscores are ignored. For
example, the method <span class="code">hello</span> maps to the keyword name
<span class="name">Hello</span>, <span class="name">hello</span> or even <span class="name">h e l l o</span>. Similarly both the
<span class="code">do_nothing</span> and <span class="code">doNothing</span> methods can be used as the
<span class="name">Do Nothing</span> keyword in the test data.</p>
<p>Example Python library implemented as a module in the <span class="path">MyLibrary.py</span> file:</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&quot;Hello, </span><span class="si">%s</span><span class="s">!&quot;</span> <span class="o">%</span> <span class="n">name</span>

<span class="k">def</span> <span class="nf">do_nothing</span><span class="p">():</span>
    <span class="k">pass</span>
</pre></div>
<p>Example Java library implemented as a class in the <span class="path">MyLibrary.java</span> file:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyLibrary</span> <span class="o">{</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">hello</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">)</span> <span class="o">{</span>
        <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;Hello, &quot;</span> <span class="o">+</span> <span class="n">name</span> <span class="o">+</span> <span class="s">&quot;!&quot;</span><span class="o">);</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">doNothing</span><span class="o">()</span> <span class="o">{</span>
    <span class="o">}</span>

<span class="o">}</span>
</pre></div>
<p>The example below illustrates how the example libraries above can be
used. If you want to try this yourself, make sure that the library is
in the <a class="reference internal" href="#adjusting-library-search-path">library search path</a>.</p>
<table border="1" class="example docutils">
<caption>Using simple example library</caption>
<colgroup>
<col width="26%" />
<col width="32%" />
<col width="21%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>MyLibrary</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="24%" />
<col width="24%" />
<col width="26%" />
<col width="26%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>My Test</td>
<td>Do Nothing</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Hello</td>
<td>world</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="keyword-arguments">
<h4><a class="toc-backref" href="#id547">Keyword arguments</a></h4>
<p>With a static and hybrid API, the information on how many arguments a
keyword needs is got directly from the method that implements it.
Libraries using the <a class="reference internal" href="#dynamic-library-api">dynamic library API</a> have other means for sharing
this information, so this section is not relevant to them.</p>
<p>The most common and also simplest situation is when a keyword needs an
exact number of arguments. In this case, both the Python and Java methods
simply take exactly those arguments. For example, a method implementing a
keyword with no arguments takes no arguments either, a method
implementing a keyword with one argument also takes one argument, and
so on.</p>
<p>Example Python keywords taking different numbers of arguments:</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">no_arguments</span><span class="p">():</span>
    <span class="k">print</span> <span class="s">&quot;Keyword got no arguments&quot;</span>

<span class="k">def</span> <span class="nf">one_argument</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&quot;Keyword got one argument &#39;</span><span class="si">%s</span><span class="s">&#39;&quot;</span> <span class="o">%</span> <span class="n">arg</span>

<span class="k">def</span> <span class="nf">multiple_arguments</span><span class="p">(</span><span class="n">a1</span><span class="p">,</span> <span class="n">a2</span><span class="p">,</span> <span class="n">a3</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&quot;Keyword got three arguments &#39;</span><span class="si">%s</span><span class="s">&#39;, &#39;</span><span class="si">%s</span><span class="s">&#39; and &#39;</span><span class="si">%s</span><span class="s">&#39;&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">a1</span><span class="p">,</span> <span class="n">a2</span><span class="p">,</span> <span class="n">a3</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="default-values-to-keywords">
<h4><a class="toc-backref" href="#id548">Default values to keywords</a></h4>
<p>It is often useful that some of the arguments that a keyword uses have
default values. Python and Java have different syntax for handling default
values to methods, and the natural syntax of these languages can be
used when creating test libraries for Robot Framework.</p>
<div class="section" id="default-values-with-python">
<h5>Default values with Python</h5>
<p>In Python a method has always exactly one implementation and possible
default values are specified in the method signature. The syntax,
which is familiar to all Python programmers, is illustrated below:</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">one_default</span><span class="p">(</span><span class="n">arg</span><span class="o">=</span><span class="s">&#39;default&#39;</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&quot;Argument has value &#39;</span><span class="si">%s</span><span class="s">&#39;&quot;</span> <span class="o">%</span> <span class="n">arg</span>

<span class="k">def</span> <span class="nf">multiple_defaults</span><span class="p">(</span><span class="n">arg1</span><span class="p">,</span> <span class="n">arg2</span><span class="o">=</span><span class="s">&#39;default 1&#39;</span><span class="p">,</span> <span class="n">arg3</span><span class="o">=</span><span class="s">&#39;default 2&#39;</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&quot;Got arguments </span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s"> and </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">arg1</span><span class="p">,</span> <span class="n">arg2</span><span class="p">,</span> <span class="n">arg3</span><span class="p">)</span>
</pre></div>
<p>The first example keyword above can be used either with zero or one
arguments. If no arguments are given, <span class="code">arg</span> gets the value
<span class="code">default</span>. If there is one argument, <span class="code">arg</span> gets that value,
and calling the keyword with more than one argument fails. In the
second example, one argument is always required, but the second and
the third one have default values, so it is possible to use the keyword
with one to three arguments.</p>
<table border="1" class="example docutils">
<caption>Using keywords with variable number of arguments</caption>
<colgroup>
<col width="16%" />
<col width="27%" />
<col width="19%" />
<col width="18%" />
<col width="19%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Defaults</td>
<td>One Default</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>One Default</td>
<td>argument</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Multiple Defaults</td>
<td>required arg</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Multiple Defaults</td>
<td>required arg</td>
<td>optional</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Multiple Defaults</td>
<td>required arg</td>
<td>optional 1</td>
<td>optional 2</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="default-values-with-java">
<h5>Default values with Java</h5>
<p>In Java one method can have several implementations with different
signatures. Robot Framework regards all these implementations as one
keyword, which can be used with different arguments. This syntax can
thus be used to provide support for the default values. This is
illustrated by the example below, which is functionally identical to
the earlier Python example:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">oneDefault</span><span class="o">(</span><span class="n">String</span> <span class="n">arg</span><span class="o">)</span> <span class="o">{</span>
    <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;Argument has value &#39;&quot;</span> <span class="o">+</span> <span class="n">arg</span> <span class="s">&quot;&#39;&quot;</span><span class="o">);</span>
<span class="o">}</span>

<span class="kd">public</span> <span class="kt">void</span> <span class="nf">oneDefault</span><span class="o">()</span> <span class="o">{</span>
    <span class="n">oneDefault</span><span class="o">(</span><span class="s">&quot;default&quot;</span><span class="o">);</span>
<span class="o">}</span>

<span class="kd">public</span> <span class="kt">void</span> <span class="nf">multipleDefaults</span><span class="o">(</span><span class="n">String</span> <span class="n">arg1</span><span class="o">,</span> <span class="n">String</span> <span class="n">arg2</span><span class="o">,</span> <span class="n">String</span> <span class="n">arg3</span><span class="o">)</span> <span class="o">{</span>
    <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;Got arguments &quot;</span> <span class="o">+</span> <span class="n">arg1</span> <span class="o">+</span> <span class="s">&quot;, &quot;</span> <span class="o">+</span> <span class="n">arg2</span> <span class="o">+</span> <span class="s">&quot; and &quot;</span> <span class="o">+</span> <span class="n">arg3</span><span class="o">);</span>
<span class="o">}</span>

<span class="kd">public</span> <span class="kt">void</span> <span class="nf">multipleDefaults</span><span class="o">(</span><span class="n">String</span> <span class="n">arg1</span><span class="o">,</span> <span class="n">String</span> <span class="n">arg2</span><span class="o">)</span> <span class="o">{</span>
    <span class="n">multipleDefaults</span><span class="o">(</span><span class="n">arg1</span><span class="o">,</span> <span class="n">arg2</span><span class="o">,</span> <span class="s">&quot;default 2&quot;</span><span class="o">);</span>
<span class="o">}</span>

<span class="kd">public</span> <span class="kt">void</span> <span class="nf">multipleDefaults</span><span class="o">(</span><span class="n">String</span> <span class="n">arg1</span><span class="o">)</span> <span class="o">{</span>
    <span class="n">multipleDefaults</span><span class="o">(</span><span class="n">arg1</span><span class="o">,</span> <span class="s">&quot;default 1&quot;</span><span class="o">);</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="id181">
<h4><a class="toc-backref" href="#id549">Variable number of arguments</a></h4>
<p>Robot Framework supports also keywords that take any number of
arguments. Similarly as with the default values, the actual syntax to use
in test libraries is different in Python and Java.</p>
<div class="section" id="variable-number-of-arguments-with-python">
<h5>Variable number of arguments with Python</h5>
<p>Python supports methods accepting any number of arguments. The same
syntax works in libraries and, as the examples below show, it can also
be combined with other ways of specifying arguments:</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">any_arguments</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&quot;Got arguments:&quot;</span>
    <span class="k">for</span> <span class="n">arg</span> <span class="ow">in</span> <span class="n">args</span><span class="p">:</span>
        <span class="k">print</span> <span class="n">arg</span>

<span class="k">def</span> <span class="nf">one_required</span><span class="p">(</span><span class="n">required</span><span class="p">,</span> <span class="o">*</span><span class="n">others</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&quot;Required: </span><span class="si">%s</span><span class="se">\n</span><span class="s">Others:&quot;</span> <span class="o">%</span> <span class="n">required</span>
    <span class="k">for</span> <span class="n">arg</span> <span class="ow">in</span> <span class="n">others</span><span class="p">:</span>
        <span class="k">print</span> <span class="n">arg</span>

<span class="k">def</span> <span class="nf">also_defaults</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">def1</span><span class="o">=</span><span class="s">&quot;default 1&quot;</span><span class="p">,</span> <span class="n">def2</span><span class="o">=</span><span class="s">&quot;default 2&quot;</span><span class="p">,</span> <span class="o">*</span><span class="n">rest</span><span class="p">):</span>
    <span class="k">print</span> <span class="n">req</span><span class="p">,</span> <span class="n">def1</span><span class="p">,</span> <span class="n">def2</span><span class="p">,</span> <span class="n">rest</span>
</pre></div>
<table border="1" class="example docutils">
<caption>Using keywords with a variable number of arguments</caption>
<colgroup>
<col width="22%" />
<col width="19%" />
<col width="19%" />
<col width="18%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Varargs</td>
<td>Any Arguments</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Any Arguments</td>
<td>argument</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Any Arguments</td>
<td>arg 1</td>
<td>arg 2</td>
<td>arg 2</td>
</tr>
<tr><td></td>
<td>...</td>
<td>arg 4</td>
<td>arg 5</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>One Required</td>
<td>required arg</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>One Required</td>
<td>required arg</td>
<td>another arg</td>
<td>yet another</td>
</tr>
<tr><td></td>
<td>Also Defaults</td>
<td>required</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Also Defaults</td>
<td>required</td>
<td>these two</td>
<td>have defaults</td>
</tr>
<tr><td></td>
<td>Also Defaults</td>
<td>1</td>
<td>2</td>
<td>3</td>
</tr>
<tr><td></td>
<td>...</td>
<td>4</td>
<td>5</td>
<td>6</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="variable-number-of-arguments-with-java">
<h5>Variable number of arguments with Java</h5>
<p>Robot supports Java varargs syntax for defining variable number of
arguments.  Robot also will translate an array as the last argument in
a keyword signature as a list of variable number of arguments. In this
case, all leftover arguments to the keyword are packed into the
list. This also works if the keyword is used with one argument less
than the actual number of arguments in the signature - in this case
the array at the end will be empty.</p>
<p>Robot's support for variable number of arguments in Java has one
limitation: it only works if the method has only one signature. Thus
it is not possible to have a Java keyword that has both the default
values and a variable number of arguments.  Of course, having a number
of required arguments is still possible, as the examples below
illustrate:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">anyNumberOfArguments</span><span class="o">(</span><span class="n">String</span><span class="o">...</span> <span class="n">varargs</span><span class="o">)</span> <span class="o">{</span>
    <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;Got arguments:&quot;</span><span class="o">);</span>
    <span class="k">for</span> <span class="o">(</span><span class="n">String</span> <span class="nl">arg:</span> <span class="n">varargs</span><span class="o">)</span> <span class="o">{</span>
        <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">arg</span><span class="o">);</span>
    <span class="o">}</span>
<span class="o">}</span>

<span class="kd">public</span> <span class="kt">void</span> <span class="nf">oneArgumentRequired</span><span class="o">(</span><span class="n">String</span> <span class="n">required</span><span class="o">,</span> <span class="n">String</span><span class="o">...</span> <span class="n">others</span><span class="o">)</span> <span class="o">{</span>
    <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;Required: &quot;</span> <span class="o">+</span> <span class="n">required</span> <span class="o">+</span> <span class="s">&quot;\nOthers:&quot;</span><span class="o">);</span>
    <span class="k">for</span> <span class="o">(</span><span class="n">String</span> <span class="nl">arg:</span> <span class="n">others</span><span class="o">)</span> <span class="o">{</span>
        <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">arg</span><span class="o">);</span>
    <span class="o">}</span>
<span class="o">}</span>

<span class="kd">public</span> <span class="kt">void</span> <span class="nf">usingAnArray</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="o">{</span>
    <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;Got arguments:&quot;</span><span class="o">);</span>
    <span class="k">for</span> <span class="o">(</span><span class="n">String</span> <span class="nl">arg:</span> <span class="n">args</span><span class="o">)</span> <span class="o">{</span>
        <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">arg</span><span class="o">);</span>
    <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="argument-types">
<h4><a class="toc-backref" href="#id550">Argument types</a></h4>
<p>Normally keyword arguments come to Robot Framework as strings. If
keywords require some other types, it is possible to either use
<a class="reference internal" href="#variables">variables</a> or convert strings to required types inside keywords. With
<a class="reference internal" href="#argument-types-with-java">Java keywords</a> base types are also coerced automatically.</p>
<div class="section" id="argument-types-with-python">
<h5>Argument types with Python</h5>
<p>Because arguments in Python do not have any type information, there is
no possibility to automatically convert strings to other types when
using Python libraries. Calling a Python method implementing a keyword
with a correct number of arguments always succeeds, but the execution
fails later if the arguments are incompatible. Luckily with Python it
is simple to convert arguments to suitable types inside keywords:</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">connect_to_host</span><span class="p">(</span><span class="n">address</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">25</span><span class="p">):</span>
    <span class="n">port</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">port</span><span class="p">)</span>
    <span class="c"># ...</span>
</pre></div>
</div>
<div class="section" id="argument-types-with-java">
<h5>Argument types with Java</h5>
<p>Arguments to Java methods have types, and all the base types are
handled automatically. This means that arguments that are normal
strings in the test data are coerced to correct type at runtime. The
types that can be coerced are:</p>
<ul class="simple">
<li>integer types (<span class="code">byte</span>, <span class="code">short</span>, <span class="code">int</span>, <span class="code">long</span>)</li>
<li>floating point types (<span class="code">float</span> and <span class="code">double</span>)</li>
<li>the <span class="code">boolean</span> type</li>
<li>object versions of the above types e.g. <span class="code">java.lang.Integer</span></li>
</ul>
<p>The coercion is done for arguments that have the same or compatible
type across all the signatures of the keyword method. In the following
example, the conversion can be done for keywords <span class="code">doubleArgument</span>
and <span class="code">compatibleTypes</span>, but not for <span class="code">conflictingTypes</span>.</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">doubleArgument</span><span class="o">(</span><span class="kt">double</span> <span class="n">arg</span><span class="o">)</span> <span class="o">{}</span>

<span class="kd">public</span> <span class="kt">void</span> <span class="nf">compatibleTypes</span><span class="o">(</span><span class="n">String</span> <span class="n">arg1</span><span class="o">,</span> <span class="n">Integer</span> <span class="n">arg2</span><span class="o">)</span> <span class="o">{}</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">compatibleTypes</span><span class="o">(</span><span class="n">String</span> <span class="n">arg2</span><span class="o">,</span> <span class="n">Integer</span> <span class="n">arg2</span><span class="o">,</span> <span class="n">Boolean</span> <span class="n">arg3</span><span class="o">)</span> <span class="o">{}</span>

<span class="kd">public</span> <span class="kt">void</span> <span class="nf">conflictingTypes</span><span class="o">(</span><span class="n">String</span> <span class="n">arg1</span><span class="o">,</span> <span class="kt">int</span> <span class="n">arg2</span><span class="o">)</span> <span class="o">{}</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">conflictingTypes</span><span class="o">(</span><span class="kt">int</span> <span class="n">arg1</span><span class="o">,</span> <span class="n">String</span> <span class="n">arg2</span><span class="o">)</span> <span class="o">{}</span>
</pre></div>
<p>The coercion works with the numeric types if the test data has a
string containing a number, and with the boolean type the data must
contain either string <span class="code">true</span> or <span class="code">false</span>. Coercion is only
done if the original value was a string from the test data, but it is
of course still possible to use variables containing correct types with
these keywords. Using variables is the only option if keywords have
conflicting signatures.</p>
<table border="1" class="example docutils">
<caption>Using automatic type coercion</caption>
<colgroup>
<col width="15%" />
<col width="24%" />
<col width="18%" />
<col width="14%" />
<col width="29%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Coercion</td>
<td>Double Argument</td>
<td>3.14</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Double Argument</td>
<td>2e16</td>
<td>&nbsp;</td>
<td># scientific notation</td>
</tr>
<tr><td></td>
<td>Compatible Types</td>
<td>Hello, world!</td>
<td>1234</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Compatible Types</td>
<td>Hi again!</td>
<td>-10</td>
<td>true</td>
</tr>
<tr><td></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>No Coercion</td>
<td>Double Argument</td>
<td>${3.14}</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td></td>
<td>Conflicting Types</td>
<td>1</td>
<td>${2}</td>
<td># must use variables</td>
</tr>
<tr><td></td>
<td>Conflicting Types</td>
<td>${1}</td>
<td>2</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="section" id="communicating-with-robot-framework">
<h3><a class="toc-backref" href="#id551">4.1.4&nbsp;&nbsp;&nbsp;Communicating with Robot Framework</a></h3>
<p>After a method implementing a keyword is called, it can use any
mechanism to communicate with the system under test. It can then also
send messages to Robot Framework's log file, return information that
can be saved to variables and, most importantly, report if the
keyword passed or not.</p>
<div class="section" id="reporting-keyword-status">
<h4><a class="toc-backref" href="#id552">Reporting keyword status</a></h4>
<p>Reporting keyword status is done simply using exceptions. If an executed
method raises an exception, the keyword status is <span class="msg">FAIL</span>, and if it
returns normally, the status is <span class="msg">PASS</span>.</p>
<p>The error message shown in logs, reports and the console is created
from the exception type and its message. With generic exceptions (for
example, <span class="code">AssertionError</span>, <span class="code">Exception</span>, and
<span class="code">RuntimeError</span>), only the exception message is used, and with
others, the message is created in the format <span class="msg">ExceptionType:
Actual message</span>. In both cases, it is important for the users that the
exception message is as informative as possible.</p>
<p>If the error message is longer than 40 lines, it will be automatically
cut from the middle to prevent reports from getting too long and
difficult to read. The full error message is always shown in the log
message of the failed keyword.</p>
<p>The traceback of the exception is also logged using <span class="msg">DEBUG</span> <a class="reference internal" href="#log-levels">log level</a>.
These messages are not visible in log files by default because they are very
rarely interesting for normal users. When developing libraries, it is often a
good idea to run tests using <span class="cli">--loglevel DEBUG</span>.</p>
</div>
<div class="section" id="stopping-test-execution">
<h4><a class="toc-backref" href="#id553">Stopping test execution</a></h4>
<p>Starting from Robot Framework 2.5 it is possible to fail a test case so that
<a class="reference internal" href="#stopping-test-execution-gracefully">the whole test execution is stopped</a>. This is done simply by having a special
<span class="code">ROBOT_EXIT_ON_FAILURE</span> attribute with <span class="code">True</span> value set on the
exception raised from the keyword. This is illustrated in the examples below.</p>
<p>Python:</p>
<div class="highlight"><pre><span class="k">class</span> <span class="nc">MyFatalError</span><span class="p">(</span><span class="ne">RuntimeError</span><span class="p">):</span>
    <span class="n">ROBOT_EXIT_ON_FAILURE</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
<p>Java:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyFatalError</span> <span class="kd">extends</span> <span class="n">RuntimeException</span> <span class="o">{</span>
    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="kt">boolean</span> <span class="n">ROBOT_EXIT_ON_FAILURE</span> <span class="o">=</span> <span class="kc">true</span><span class="o">;</span>
<span class="o">}</span>
</pre></div>
</div>
<div class="section" id="continuing-test-execution-despite-of-failures">
<h4><a class="toc-backref" href="#id554">Continuing test execution despite of failures</a></h4>
<p>Starting from Robot Framework 2.5 it is possible to <a class="reference internal" href="#continue-on-failure">continue test
execution even when there are failures</a>. The way to signal this from
test libraries is adding a special <span class="code">ROBOT_CONTINUE_ON_FAILURE</span>
attribute with <span class="code">True</span> value to the exception used to communicate
the failure. This is demonstrated by the examples below.</p>
<p>Python:</p>
<div class="highlight"><pre><span class="k">class</span> <span class="nc">MyContinuableError</span><span class="p">(</span><span class="ne">RuntimeError</span><span class="p">):</span>
    <span class="n">ROBOT_CONTINUE_ON_FAILURE</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
<p>Java:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyContinuableError</span> <span class="kd">extends</span> <span class="n">RuntimeException</span> <span class="o">{</span>
    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="kt">boolean</span> <span class="n">ROBOT_CONTINUE_ON_FAILURE</span> <span class="o">=</span> <span class="kc">true</span><span class="o">;</span>
<span class="o">}</span>
</pre></div>
</div>
<div class="section" id="logging-information">
<h4><a class="toc-backref" href="#id555">Logging information</a></h4>
<p>Exception messages are not the only way to give information to the
users. In addition to them, methods can also send messages to <a class="reference internal" href="#log-file">log
files</a> simply by writing to the standard output stream (stdout) or to
the standard error stream (stderr), and they can even use different
<a class="reference internal" href="#log-levels">log levels</a>. Another, and often better, logging possibility is using
the <a class="reference internal" href="#programmatic-logging-apis">programmatic logging APIs</a>.</p>
<p>By default, everything written by a method into the standard output is
written to the log file as a single entry with the log level
<span class="msg">INFO</span>. Messages written into the standard error are handled
similarly otherwise, but they are echoed back to the original stderr
after the keyword execution has finished. It is thus possible to use
the stderr if you need some messages to be visible on the console where
tests are executed.</p>
<div class="section" id="using-log-levels">
<h5>Using log levels</h5>
<p>To use other log levels than <span class="msg">INFO</span>, or to create several
messages, specify the log level explicitly by embedding the level into
the message in the format <span class="code">*LEVEL* Actual log message</span>, where
<span class="code">*LEVEL*</span> must be in the beginning of a line and <span class="msg">LEVEL</span> is
one of the available logging levels <span class="msg">TRACE</span>, <span class="msg">DEBUG</span>,
<span class="msg">INFO</span>, <span class="msg">WARN</span> and <span class="msg">HTML</span>.</p>
</div>
<div class="section" id="warnings">
<h5>Warnings</h5>
<p>Messages with <span class="msg">WARN</span> level are automatically written into <a class="reference internal" href="#errors-and-warnings-during-execution">the
console and into separate Test Execution Errors section</a> in log
files. This makes warnings more visible than other messages and allows
using them for reporting important but non-critical problems to users.</p>
</div>
<div class="section" id="logging-html">
<h5>Logging HTML</h5>
<p>Everything normally logged by the library will be converted into a
format that can be safely represented as HTML. For example,
<span class="code">&lt;b&gt;foo&lt;/b&gt;</span> will be displayed in the log exactly like that and
not as <strong>foo</strong>. If libraries want to use formatting, links, display
images and so on, they can use a special pseudo log level
<span class="msg">HTML</span>. Robot Framework will write these messages directly into
the log with the <span class="msg">INFO</span> level, so they can use any HTML syntax
they want. Notice that this feature needs to be used with care,
because, for example, one badly placed <span class="code">&lt;/table&gt;</span> tag can ruin
the log file quite badly.</p>
<p>When using the <a class="reference internal" href="#public-logging-api">public logging API</a>, various logging methods
have optional <span class="code">html</span> attribute that can be set to <span class="code">True</span>
to enable logging in HTML format.</p>
</div>
<div class="section" id="timestamps">
<h5>Timestamps</h5>
<p>By default messages logged via the standard output or error streams
get their timestamps when the executed keyword ends. This means that
the timestamps are not accurate and debugging problems especially with
longer running keywords can be problematic.</p>
<p>Starting from Robot Framework 2.6 keywords have a possibility to add
an accurate timestamp to the messages they log if there is a need. The
timestamp must be given as milliseconds since the <a class="reference external" href="http://en.wikipedia.org/wiki/Unix_epoch">Unix epoch</a> and it
must be placed after the <a class="reference internal" href="#using-log-levels">log level</a> separated from it with a colon:</p>
<pre class="literal-block">
*INFO:1308435758660* Message with timestamp
*HTML:1308435758661* &lt;b&gt;HTML&lt;/b&gt; message with timestamp
</pre>
<p>As illustrated by the examples below, adding the timestamp is easy
both using Python and Java. If you are using Python, it is, however,
even easier to get accurate timestamps using the <a class="reference internal" href="#programmatic-logging-apis">programmatic logging
APIs</a>. A big benefit of adding timestamps explicitly is that this
approach works also with the <a class="reference internal" href="#remote-library-interface">remote library interface</a>.</p>
<p>Python:</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">time</span>

<span class="k">def</span> <span class="nf">example_keyword</span><span class="p">():</span>
    <span class="k">print</span> <span class="s">&#39;*INFO:</span><span class="si">%d</span><span class="s">* Message with timestamp&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span><span class="o">*</span><span class="mi">1000</span><span class="p">)</span>
</pre></div>
<p>Java:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">exampleKeyword</span><span class="o">()</span> <span class="o">{</span>
    <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;*INFO:&quot;</span> <span class="o">+</span> <span class="n">System</span><span class="o">.</span><span class="na">currentTimeMillis</span><span class="o">()</span> <span class="o">+</span> <span class="s">&quot;* Message with timestamp&quot;</span><span class="o">);</span>
<span class="o">}</span>
</pre></div>
</div>
<div class="section" id="logging-to-console">
<h5>Logging to console</h5>
<p>If libraries need to write something to the console they have several
options. As already discussed, warnings and all messages written to the
standard error stream are written both to the log file and to the
console. Both of these options have a limitation that the messages end
up to the console only after the currently executing keyword
finishes. A bonus is that these approaches work both with Python and
Java based libraries.</p>
<p>Another option, that is only available with Python, is writing
messages to <span class="code">sys.__stdout__</span> or <span class="code">sys.__stderr__</span>. When
using this approach, messages are written to the console immediately
and are not written to the log file at all:</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">sys</span>

<span class="k">def</span> <span class="nf">my_keyword</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
   <span class="n">sys</span><span class="o">.</span><span class="n">__stdout__</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;Got arg </span><span class="si">%s</span><span class="se">\n</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">arg</span><span class="p">)</span>
</pre></div>
<p>The final option is using the <a class="reference internal" href="#public-logging-api">public logging API</a>:</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">robot.api</span> <span class="kn">import</span> <span class="n">logger</span>

<span class="k">def</span> <span class="nf">log_to_console</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
   <span class="n">logger</span><span class="o">.</span><span class="n">console</span><span class="p">(</span><span class="s">&#39;Got arg </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">arg</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">log_to_console_and_log_file</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>
   <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s">&#39;Got arg </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">arg</span><span class="p">,</span> <span class="n">also_console</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="logging-example">
<h5>Logging example</h5>
<p>In most cases, the <span class="msg">INFO</span> level is adequate. The levels below it,
<span class="msg">DEBUG</span> and <span class="msg">TRACE</span>, are useful for writing debug information.
These messages are normally not shown, but they can facilitate debugging
possible problems in the library itself. The <span class="msg">WARN</span> level can
be used to make messages more visible and <span class="msg">HTML</span> is useful if any
kind of formatting is needed.</p>
<p>The following examples clarify how logging with different levels
works. Java programmers should regard the code <span class="code">print 'message'</span>
as pseudocode meaning <span class="code">System.out.println(&quot;message&quot;);</span>.</p>
<div class="highlight"><pre><span class="k">print</span> <span class="s">&#39;Hello from a library.&#39;</span>
<span class="k">print</span> <span class="s">&#39;*WARN* Warning from a library.&#39;</span>
<span class="k">print</span> <span class="s">&#39;*INFO* Hello again!&#39;</span>
<span class="k">print</span> <span class="s">&#39;This will be part of the previous message.&#39;</span>
<span class="k">print</span> <span class="s">&#39;*INFO* This is a new message.&#39;</span>
<span class="k">print</span> <span class="s">&#39;*INFO* This is &lt;b&gt;normal text&lt;/b&gt;.&#39;</span>
<span class="k">print</span> <span class="s">&#39;*HTML* This is &lt;b&gt;bold&lt;/b&gt;.&#39;</span>
<span class="k">print</span> <span class="s">&#39;*HTML* &lt;a href=&quot;http://robotframework.org&quot;&gt;Robot Framework&lt;/a&gt;&#39;</span>
</pre></div>
<table class="messages">
  <tr>
    <td class="time">16:18:42.123</td>
    <td class="info level">INFO</td>
    <td class="msg">Hello from a library.</td>
  </tr>
  <tr>
    <td class="time">16:18:42.123</td>
    <td class="warn level">WARN</td>
    <td class="msg">Warning from a library.</td>
  </tr>
  <tr>
    <td class="time">16:18:42.123</td>
    <td class="info level">INFO</td>
    <td class="msg">Hello again!<br>This will be part of the previous message.</td>
  </tr>
  <tr>
    <td class="time">16:18:42.123</td>
    <td class="info level">INFO</td>
    <td class="msg">This is a new message.</td>
  </tr>
  <tr>
    <td class="time">16:18:42.123</td>
    <td class="info level">INFO</td>
    <td class="msg">This is &lt;b&gt;normal text&lt;/b&gt;.</td>
  </tr>
  <tr>
    <td class="time">16:18:42.123</td>
    <td class="info level">INFO</td>
    <td class="msg">This is <b>bold</b>.</td>
  </tr>
  <tr>
    <td class="time">16:18:42.123</td>
    <td class="info level">INFO</td>
    <td class="msg"><a href="http://robotframework.org">Robot Framework</a></td>
  </tr>
</table></div>
</div>
<div class="section" id="programmatic-logging-apis">
<h4><a class="toc-backref" href="#id556">Programmatic logging APIs</a></h4>
<p>Programmatic APIs provide somewhat cleaner way to log information than
using the standard output and error streams. Currently these
interfaces are available only to Python bases test libraries.</p>
<div class="section" id="public-logging-api">
<h5>Public logging API</h5>
<p>Robot Framework 2.6 has a new Python based logging API for writing
messages to the log file and to the console. Test libraries can use
this API like <span class="code">logger.info('My message')</span> instead of logging
through the standard output like <span class="code">print '*INFO* My message'</span>. In
addition to a programmatic interface being a lot cleaner to use, this
API has a benefit that the log messages have accurate <a class="reference internal" href="#timestamps">timestamps</a>. An
obvious limitation is that test libraries using this logging API have
a dependency to Robot Framework.</p>
<p>The public logging API is documented as part of the API documentation but
here is a simple usage example:</p>
<!-- FIXME: Link to API docs. -->
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">robot.api</span> <span class="kn">import</span> <span class="n">logger</span>

<span class="k">def</span> <span class="nf">my_keyword</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
    <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s">&#39;Got argument </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">arg</span><span class="p">)</span>
    <span class="n">do_something</span><span class="p">()</span>
    <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s">&#39;&lt;i&gt;This&lt;/i&gt; is a boring example&#39;</span><span class="p">,</span> <span class="n">html</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">logger</span><span class="o">.</span><span class="n">console</span><span class="p">(</span><span class="s">&#39;Hello, console!&#39;</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="using-python-s-standard-logging-module">
<h5>Using Python's standard <span class="code">logging</span> module</h5>
<p>In addition to the new <a class="reference internal" href="#public-logging-api">public logging API</a>, Robot Framework 2.6 also
added a built-in support to Python's standard <a class="reference external" href="http://docs.python.org/library/logging.html">logging</a> module. This
works so that all messages that are received by the root logger of the
module are automatically propagated to Robot Framework's log
file. Also this API produces log messages with accurate <a class="reference internal" href="#timestamps">timestamps</a>,
but logging HTML messages or writing messages to the console are not
supported. A big benefit, illustrated also by the simple example
below, is that using this logging API creates no dependency to Robot
Framework.</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">logging</span>

<span class="k">def</span> <span class="nf">my_keyword</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
    <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s">&#39;Got argument </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">arg</span><span class="p">)</span>
    <span class="n">do_something</span><span class="p">()</span>
    <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s">&#39;This is a boring example&#39;</span><span class="p">)</span>
</pre></div>
<p>The <span class="code">logging</span> module has slightly different log levels than
Robot Framework. Its levels <span class="msg">DEBUG</span> and <span class="msg">INFO</span> are mapped
directly to the matching Robot Framework log levels and <span class="msg">WARNING</span>
and everything above is mapped to <span class="msg">WARN</span>. Custom levels below
<span class="msg">DEBUG</span> are mapped to <span class="msg">DEBUG</span> and everything between
<span class="msg">DEBUG</span> and <span class="msg">WARNING</span> is mapped to <span class="msg">INFO</span>.</p>
</div>
</div>
<div class="section" id="logging-during-library-initialization">
<h4><a class="toc-backref" href="#id557">Logging during library initialization</a></h4>
<p>Libraries can also log during the test library import and initialization.
These messages do not appear in the <a class="reference internal" href="#log-file">log file</a> like the normal log messages,
but are instead written to the <a class="reference internal" href="#system-log">syslog</a>. This allows logging any kind of
useful debug information about the library initialization. Messages logged
using the <span class="msg">WARN</span> level are also visible in the <a class="reference internal" href="#errors-and-warnings-during-execution">test execution errors</a>
section in the log file.</p>
<p>Logging during the import and initialization is possible both using the
<a class="reference internal" href="#logging-information">standard output and error streams</a> and the <a class="reference internal" href="#programmatic-logging-apis">programmatic logging APIs</a>.
Both of these are demonstrated below.</p>
<p>Java library logging via stdout during initialization:</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">LoggingDuringInitialization</span> <span class="o">{</span>

    <span class="kd">public</span> <span class="nf">LoggingDuringInitialization</span><span class="o">()</span> <span class="o">{</span>
        <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;*INFO* Initializing library&quot;</span><span class="o">);</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">keyword</span><span class="o">()</span> <span class="o">{</span>
        <span class="c1">// ...</span>
    <span class="o">}</span>
<span class="o">}</span>
</pre></div>
<p>Python library logging using the logging API during import:</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">robot.api</span> <span class="kn">import</span> <span class="n">logger</span>

<span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s">&quot;Importing library&quot;</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">keyword</span><span class="p">():</span>
    <span class="c"># ...</span>
</pre></div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">If you log something during initialization, i.e. in Python
<span class="code">__init__</span> or in Java constructor, the messages may be
logged multiple times depending on the <a class="reference internal" href="#test-library-scope">test library scope</a>.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The support for writing log messages to the syslog during the
library initialization is a new feature in Robot Framework 2.6.</p>
</div>
</div>
<div class="section" id="returning-values">
<h4><a class="toc-backref" href="#id558">Returning values</a></h4>
<p>The final way for keywords to communicate back to the core framework
is returning information retrieved from the system under test or
generated by some other means. The returned values can be <a class="reference internal" href="#return-values-from-keywords">assigned to
variables</a> in the test data and then used as inputs for other keywords,
even from different test libraries.</p>
<p>Values are returned using the <span class="code">return</span> statement both from
the Python and Java methods. Normally, one value is assigned into one
<a class="reference internal" href="#scalar-variables">scalar variable</a>, as illustrated in the example below. This example
also illustrates that it is possible to return any objects and to use
<a class="reference internal" href="#extended-variable-syntax">extended variable syntax</a> to access object attributes.</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">mymodule</span> <span class="kn">import</span> <span class="n">MyObject</span>

<span class="k">def</span> <span class="nf">return_string</span><span class="p">():</span>
    <span class="k">return</span> <span class="s">&quot;Hello, world!&quot;</span>

<span class="k">def</span> <span class="nf">return_object</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">MyObject</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
</pre></div>
<table border="1" class="example docutils">
<caption>Return one value from keywords</caption>
<colgroup>
<col width="36%" />
<col width="33%" />
<col width="31%" />
</colgroup>
<tbody valign="top">
<tr><td>${string} =</td>
<td>Return String</td>
<td>&nbsp;</td>
</tr>
<tr><td>Should Be Equal</td>
<td>${string}</td>
<td>Hello, world!</td>
</tr>
<tr><td>${object} =</td>
<td>Return Object</td>
<td>Robot</td>
</tr>
<tr><td>Should Be Equal</td>
<td>${object.name}</td>
<td>Robot</td>
</tr>
</tbody>
</table>
<p>Keywords can also return values so that they can be assigned into
several <a class="reference internal" href="#scalar-variables">scalar variables</a> at once, into <a class="reference internal" href="#list-variables">a list variable</a>, or
into scalar variables and a list variable. All these usages require
that returned values are Python lists or tuples or
in Java arrays, Lists, or Iterators.</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">return_two_values</span><span class="p">():</span>
    <span class="k">return</span> <span class="s">&#39;first value&#39;</span><span class="p">,</span> <span class="s">&#39;second value&#39;</span>

<span class="k">def</span> <span class="nf">return_multiple_values</span><span class="p">():</span>
    <span class="k">return</span> <span class="p">[</span><span class="s">&#39;a&#39;</span><span class="p">,</span> <span class="s">&#39;list&#39;</span><span class="p">,</span> <span class="s">&#39;of&#39;</span><span class="p">,</span> <span class="s">&#39;strings&#39;</span><span class="p">]</span>
</pre></div>
<table border="1" class="example docutils">
<caption>Returning multiple values</caption>
<colgroup>
<col width="21%" />
<col width="24%" />
<col width="24%" />
<col width="31%" />
</colgroup>
<tbody valign="top">
<tr><td>${var1}</td>
<td>${var2} =</td>
<td>Return Two Values</td>
<td>&nbsp;</td>
</tr>
<tr><td>Should Be Equal</td>
<td>${var1}</td>
<td>first value</td>
<td>&nbsp;</td>
</tr>
<tr><td>Should Be Equal</td>
<td>${var2}</td>
<td>second value</td>
<td>&nbsp;</td>
</tr>
<tr><td>&#64;{list} =</td>
<td>Return Two Values</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Should Be Equal</td>
<td>&#64;{list}[0]</td>
<td>first value</td>
<td>&nbsp;</td>
</tr>
<tr><td>Should Be Equal</td>
<td>&#64;{list}[1]</td>
<td>second value</td>
<td>&nbsp;</td>
</tr>
<tr><td>${s1}</td>
<td>${s2}</td>
<td>&#64;{li} =</td>
<td>Return Multiple Values</td>
</tr>
<tr><td>Should Be Equal</td>
<td>${s1} ${s2}</td>
<td>a list</td>
<td>&nbsp;</td>
</tr>
<tr><td>Should Be Equal</td>
<td>&#64;{li}[0] &#64;{li}[1]</td>
<td>of strings</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="communication-when-using-threads">
<h4><a class="toc-backref" href="#id559">Communication when using threads</a></h4>
<p>If a library uses threads, it should generally communicate with the
framework only from the main thread. If a worker thread has, for
example, a failure to report or something to log, it should pass the
information first to the main thread, which can then use exceptions or
other mechanisms explained in this section for communication with the
framework.</p>
<p>This is especially important when threads are run on background while
other keywords are running. Results of communicating with the
framework in that case are undefined and can in works case cause a
crash or a corrupted output file. If a keyword starts something on
background, there should be another keyword that checks the status of
the worker thread and reports gathered information accordingly.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Messages logged by non-main threads using the <a class="reference internal" href="#programmatic-logging-apis">programmatic
logging APIs</a> are silently ignored starting from Robot
Framework 2.6.2.</p>
</div>
</div>
</div>
<div class="section" id="distributing-test-libraries">
<h3><a class="toc-backref" href="#id560">4.1.5&nbsp;&nbsp;&nbsp;Distributing test libraries</a></h3>
<div class="section" id="documenting-libraries">
<h4><a class="toc-backref" href="#id561">Documenting libraries</a></h4>
<p>A test library without documentation about what keywords it
contains and what those keywords do is rather useless. To ease
maintenance, it is highly recommended that library documentation is
included in the source code and generated from it. Basically, that
means using <a class="reference external" href="http://www.python.org/dev/peps/pep-0257">docstrings</a> with Python and <a class="reference external" href="http://java.sun.com/j2se/javadoc/writingdoccomments/index.html">Javadoc</a> with Java, as in
the examples below.</p>
<div class="highlight"><pre><span class="k">class</span> <span class="nc">MyLibrary</span><span class="p">:</span>
    <span class="sd">&quot;&quot;&quot;This is an example library with some documentation.&quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="nf">keyword_with_short_documentation</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">argument</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;This keyword has only a short documentation&quot;&quot;&quot;</span>
        <span class="k">pass</span>

    <span class="k">def</span> <span class="nf">keyword_with_longer_documentation</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;First line of the documentation is here.</span>

<span class="sd">        Longer documentation continues here and it can contain</span>
<span class="sd">        multiple lines or paragraphs.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">pass</span>
</pre></div>
<div class="highlight"><pre><span class="cm">/**</span>
<span class="cm"> *  This is an example library with some documentation.</span>
<span class="cm"> */</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyLibrary</span> <span class="o">{</span>

    <span class="cm">/**</span>
<span class="cm">     * This keyword has only a short documentation</span>
<span class="cm">     */</span>
    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">keywordWithShortDocumentation</span><span class="o">(</span><span class="n">String</span> <span class="n">argument</span><span class="o">)</span> <span class="o">{</span>
    <span class="o">}</span>

    <span class="cm">/**</span>
<span class="cm">     * First line of the documentation is here.</span>
<span class="cm">     *</span>
<span class="cm">     * Longer documentation continues here and it can contain</span>
<span class="cm">     * multiple lines or paragraphs.</span>
<span class="cm">     */</span>
    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">keywordWithLongerDocumentation</span><span class="o">()</span> <span class="o">{</span>
    <span class="o">}</span>

<span class="o">}</span>
</pre></div>
<p>Both Python and Java have tools for creating an API documentation of a
library documented as above. However, outputs from these tools can be slightly
technical for some users. Another alternative is using Robot
Framework's own documentation tool <a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a>. This tool can
create a library documentation from both Python and Java libraries
using the static library API, such as the ones above, but it also handles
libraries using the <a class="reference internal" href="#dynamic-library-api">dynamic library API</a> and <a class="reference internal" href="#hybrid-library-api">hybrid library API</a>.</p>
<p>The first line of a keyword documentation is used for a special
purpose and should contain a short overall description of the
keyword. It is used as a <em>short documentation</em>, for example as a tool
tip, by <a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> and also shown in the test logs. However, the latter
does not work with Java libraries using the static API,
because their documentations are lost in compilation and not available
at runtime.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">If you want to use non-ASCII charactes in the documentation of
Python libraries, you must either use UTF-8 as your <a class="reference external" href="http://www.python.org/dev/peps/pep-0263">source code
encoding</a> or create docstrings as Unicode.</p>
</div>
</div>
<div class="section" id="testing-libraries">
<h4><a class="toc-backref" href="#id562">Testing libraries</a></h4>
<p>Any non-trivial test library needs to be thoroughly tested to prevent
bugs in them. Of course, this testing should be automated to make it
easy to rerun tests when libraries are changed.</p>
<p>Both Python and Java have excellent unit testing tools, and they suite
very well for testing libraries. There are no major differences in
using them for this purpose compared to using them for some other
testing. The developers familiar with these tools do not need to learn
anything new, and the developers not familiar with them should learn
them anyway.</p>
<p>It is also easy to use Robot Framework itself for testing libraries
and that way have actual end-to-end acceptance tests for them. There are
plenty of useful keywords in the <a class="reference internal" href="#builtin-library">BuiltIn library</a> for this
purpose. One worth mentioning specifically is <span class="name">Run Keyword And Expect
Error</span>, which is useful for testing that keywords report errors
correctly.</p>
<p>Whether to use a unit- or acceptance-level testing approach depends on
the context. If there is a need to simulate the actual system under
test, it is often easier on the unit level. On the other hand,
acceptance tests ensure that keywords do work through Robot
Framework. If you cannot decide, of course it is possible to use both
the approaches.</p>
</div>
<div class="section" id="packaging-libraries">
<h4><a class="toc-backref" href="#id563">Packaging libraries</a></h4>
<p>After a library is implemented, documented, and tested, it still needs
to be distributed to the users. With simple libraries consisting of a
single file, it is often enough to ask the users to copy that file
somewhere and set the <a class="reference internal" href="#adjusting-library-search-path">library search path</a> accordingly. More
complicated libraries should be packaged to make the installation
easier.</p>
<p>Since libraries are normal programming code, they can be packaged
using normal packaging tools. With Python, good options include
<a class="reference external" href="http://docs.python.org/dist/dist.html">distutils</a>, contained by Python's standard library, and the newer
<a class="reference external" href="http://peak.telecommunity.com/DevCenter/setuptools">setuptools</a>. A benefit of these tools is that library modules are
installed into a location that is automatically in the <a class="reference internal" href="#adjusting-library-search-path">library
search path</a>.</p>
<p>When using Java, it is natural to package libraries into a JAR
archive. The JAR package must be put into the <a class="reference internal" href="#adjusting-library-search-path">library search path</a>
before running tests, but it is easy to <a class="reference internal" href="#creating-start-up-scripts">create a start-up</a> script that
does that automatically.</p>
</div>
<div class="section" id="deprecating-keywords">
<h4><a class="toc-backref" href="#id564">Deprecating keywords</a></h4>
<p>Sometimes there is a need to replace existing keywords with new ones
or remove them altogether. Just informing the users about the change
may not always be enough, and it is more efficient to get warnings at
runtime. To support that, Robot Framework has a capability to mark
keywords <em>deprecated</em>. This makes it easier to find old keywords from
the test data and remove or replace them.</p>
<p>Keywords are deprecated by starting their documentation with
<span class="code">*DEPRECATED*</span>. When these keywords are executed, a warning
containing rest of the <a class="reference internal" href="#documenting-libraries">short documentation</a> is written both into
<a class="reference internal" href="#errors-and-warnings-during-execution">the console and into separate Test Execution Errors section</a> in log
files.  For example, if following keyword is executed there will be a
warning like shown below in the log file.</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">example_keyword</span><span class="p">(</span><span class="n">argument</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;*DEPRECATED* Use keyword `Other Keyword` instead.</span>

<span class="sd">    This keyword does something to given `argument` and returns the result.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">return</span> <span class="n">do_something</span><span class="p">(</span><span class="n">argument</span><span class="p">)</span>
</pre></div>
<table class="messages">
  <tr>
    <td class="time">20080911&nbsp;16:00:22.650</td>
    <td class="warn level">WARN</td>
    <td class="msg">Keyword 'SomeLibrary.Example Keyword' is deprecated. Use keyword `Other Keyword` instead.</td>
  </tr>
</table><p>This deprecation system works with most test libraries and also with
<a class="reference internal" href="#user-keyword-name-and-documentation">user keywords</a>.  The only exception are keywords implemented in a
Java test library that uses the <a class="reference internal" href="#creating-static-keywords">static library interface</a> because
their documentation is not available at runtime. With such keywords,
it possible to use user keywords as wrappers and deprecate them.</p>
<p>There is a plan to implement a tool that can use the deprecation
information for automatically replacing deprecated keywords. The tool
will most likely get the name of the new keyword from the
documentation so that it searches words inside backticks
(<span class="code">`</span>). Thus it would find <span class="name">Other Keyword</span> from the
earlier example. Note that <a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> also automatically creates
internal links using the same syntax.</p>
</div>
</div>
<div class="section" id="dynamic-library-api">
<h3><a class="toc-backref" href="#id565">4.1.6&nbsp;&nbsp;&nbsp;Dynamic library API</a></h3>
<p>The dynamic API is in most ways similar to the static API. For
example, reporting the keyword status, logging, and returning values
works exactly the same way. Most importantly, there are no differences
in importing dynamic libraries and using their keywords compared to
other libraries, so you do not even need to know what APIs the
libraries use.</p>
<p>The only difference between static and dynamic libraries is the way
how Robot Framework discovers what keywords the library implements,
what arguments and documentation they have and how those keywords are
actually executed. With the static API, all this is done using
reflection (except for the documentation of Java libraries), but
dynamic libraries have special methods that are used for these
purposes.</p>
<p>One of the benefits of the dynamic API is that you have more
flexibility in organizing your library. With the static API, you have all
keywords in one class (or module), whereas with the dynamic API, you can,
for example, implement each keyword as a separate class, if you
want. This use case is not so important with Python, because
its dynamic capabilities and multi-inheritance already give plenty of
flexibility and the <a class="reference internal" href="#hybrid-library-api">hybrid library API</a> is usually a better option.</p>
<p>Another major use case for the dynamic API is implementing a library
so that it is only a proxy for an actual library on some other
computer or another JVM. This kind of a proxy library can be very
thin, and because keyword names are got dynamically, there is no
need to update the proxy when new keywords are added into the actual
library.</p>
<p>This section explains how the dynamic API works between Robot
Framework and dynamic libraries. It does not matter for Robot
Framework how these libraries are actually implemented (for example,
how calls to the <span class="code">run_keyword</span> method are mapped to a correct
keyword implementation), and many different approaches are
possible. However, if you use Java, you may want to examine
<a class="reference internal" href="#base-classes-for-java-libraries-javalibcore">JavaTools</a> before implementing your own system. This collection of
reusable tools supports several ways of creating keywords, and it is
likely that it already has a mechanism that suites your needs.</p>
<div class="section" id="getting-keyword-names">
<h4><a class="toc-backref" href="#id566">Getting keyword names</a></h4>
<p>Dynamic libraries tell what keywords they implement with the
<span class="code">get_keyword_names</span> method. The method also has the alias
<span class="code">getKeywordNames</span> that is recommended when writing Java. This
method cannot take any arguments, and it must return a list of strings
(in Python) or a string array (in Java) containing the names of the
keywords that the library implements.</p>
<p>If the returned keyword names contain several words, they can be returned
separated with spaces or underscores, or in the camelCase format. For
example, <span class="code">['first keyword', 'second keyword']</span>,
<span class="code">['first_keyword', 'second_keyword']</span>, and
<span class="code">['firstKeyword', 'secondKeyword']</span> would all result in the keywords
<span class="name">First Keyword</span> and <span class="name">Second Keyword</span>.</p>
<p>Dynamic libraries must always have this method. If it is missing, or
if calling it fails for some reason, the library is considered a
static library, instead.</p>
</div>
<div class="section" id="running-keywords">
<h4><a class="toc-backref" href="#id567">Running keywords</a></h4>
<p>Dynamic libraries have a special <span class="code">run_keyword</span> (alias
<span class="code">runKeyword</span>) method for executing their keywords. When a
keyword from a dynamic library is used in the test data, Robot
Framework uses the library's <span class="code">run_keyword</span> method to get it
executed. This method takes two arguments. The first argument is a
string containing the name of the keyword to be executed in the same
format as returned by <span class="code">get_keyword_names</span>. The second argument is
a list of arguments (an object array in Java) given to the keyword in
the test data.</p>
<p>After the library has got the keyword name and arguments, it can
execute the keyword freely, but it must use the same mechanism to
communicate with the framework as static libraries. This
means using exceptions for reporting keyword status, logging by
writing to the standard output and using the return statement in
<span class="code">run_keyword</span> for returning something.</p>
<p>Every dynamic library must have both the <span class="code">get_keyword_names</span> and
<span class="code">run_keyword</span> methods. The rest of the methods in the dynamic
API are optional, so the example below shows a working (albeit
trivial) dynamic library.</p>
<div class="highlight"><pre><span class="k">class</span> <span class="nc">DynamicExample</span><span class="p">:</span>

    <span class="k">def</span> <span class="nf">get_keyword_names</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="p">[</span><span class="s">&#39;first keyword&#39;</span><span class="p">,</span> <span class="s">&#39;second keyword&#39;</span><span class="p">]</span>

    <span class="k">def</span> <span class="nf">run_keyword</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">args</span><span class="p">):</span>
        <span class="k">print</span> <span class="s">&quot;Running keyword </span><span class="si">%s</span><span class="s"> with arguments </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="getting-keyword-arguments">
<h4><a class="toc-backref" href="#id568">Getting keyword arguments</a></h4>
<p>If a dynamic library only implements the <span class="code">get_keyword_names</span> and
<span class="code">run_keyword</span> methods, Robot Framework does not have any information
about the arguments that the implemented keywords need. For example,
both <span class="name">First Keyword</span> and <span class="name">Second Keyword</span> in the example above
could be used with any number of arguments. This is problematic,
because most real keywords expect a certain number of keywords, and
under these circumstances they would need to check the argument counts
themselves.</p>
<p>Dynamic libraries can tell Robot Framework what arguments the keywords
that it implements actually expect using
<span class="code">get_keyword_arguments</span> (alias <span class="code">getKeywordArguments</span>)
method. This method takes the name of a keyword as an argument and returns a
list of strings (a string array in Java) containing the arguments
accepted by that keyword.</p>
<p>Similarly as static keywords, dynamic keywords can require any number
of arguments, have default values and accept a variable number of
arguments. The syntax for how to represent all these different
situations is explained in the following table. Note that the examples
use Python lists of strings, but Java developers should be able to
translate them to string arrays.</p>
<table border="1" class="tabular docutils">
<caption>Representing different arguments with <span class="code">get_keyword_arguments</span></caption>
<colgroup>
<col width="20%" />
<col width="34%" />
<col width="37%" />
<col width="8%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Expected
arguments</th>
<th class="head">How to represent</th>
<th class="head">Examples</th>
<th class="head">Min /
Max</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>No arguments</td>
<td>Empty list.</td>
<td><span class="code">[]</span></td>
<td>0/0</td>
</tr>
<tr><td>One or more
argument</td>
<td>List of strings containing
argument names.</td>
<td><span class="code">['one_argument']</span>,
<span class="code">['a1', 'a2', 'a3']</span></td>
<td>1/1,
3/3</td>
</tr>
<tr><td>Default values
for arguments</td>
<td>Default values separated
from names with <span class="code">=</span>.
Default values are always
considered to be strings.</td>
<td><span class="code">['arg=default value']</span>,
<span class="code">['a', 'b=1', 'c=2']</span></td>
<td>0/1,
1/3</td>
</tr>
<tr><td>Variable number
of arguments</td>
<td>Last argument has
<span class="code">*</span> before its name.</td>
<td><span class="code">['*arguments']</span>,
<span class="code">['a', 'b=42', '*rest']</span></td>
<td>0/any,
1/any</td>
</tr>
</tbody>
</table>
<p>When the <span class="code">get_keyword_arguments</span> is used, Robot Framework
automatically calculates how many arguments the keywords require. If a
keyword is used with an invalid number of arguments, an error occurs
and <span class="code">run_keyword</span> is not even called. The last column of the
table above shows the minimum and maximum argument counts calculated
from the presented examples.</p>
<p>The actual argument names do not matter when tests are executed,
because only argument counts are of concern to Robot Framework. On the
other hand, if the <a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> tool is used for documenting the
library, arguments are shown in the documentation, in which case they
need to have meaningful names.</p>
</div>
<div class="section" id="getting-keyword-documentation">
<h4><a class="toc-backref" href="#id569">Getting keyword documentation</a></h4>
<p>The final special method that dynamic libraries can implement is
<span class="code">get_keyword_documentation</span> (alias
<span class="code">getKeywordDocumentation</span>). It takes a keyword name as an
argument and, as the method name implies, returns its documentation as
a string.</p>
<p>The returned documentation is used similarly as the keyword
documentation string with static libraries implemented with
Python. The main use case is getting keywords' documentations into a
library documentation generated with <a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a>. Additionally,
the first line of the documentation (until the first <span class="code">\n</span>) is
shown in test logs.</p>
</div>
<div class="section" id="getting-general-library-documentation">
<h4><a class="toc-backref" href="#id570">Getting general library documentation</a></h4>
<p>The <span class="code">get_keyword_documentation</span> method can also be used for
specifying overall library documentation. This documentation is not
used when tests are executed, but it can make the documentation
generated by <a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> much better.</p>
<p>Dynamic libraries can provide both general library documentation and
documentation related to taking the library into use. The former is
got by calling <span class="code">get_keyword_documentation</span> with special value
<span class="code">__intro__</span>, and the latter is got using value
<span class="code">__init__</span>. How the documentation is presented is best tested
with <a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> in practice.</p>
<p>Python based dynamic libraries can also specify the general library
documentation directly in the code as the docstring of the library
class or its <span class="code">__init__</span> method. If non-empty documentation is
got both directly from the code and from the
<span class="code">get_keyword_documentation</span> method, the latter has higher
priority.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Getting general library documentation is supported in Robot
Framework 2.6.2 and newer.</p>
</div>
</div>
<div class="section" id="summary">
<h4><a class="toc-backref" href="#id571">Summary</a></h4>
<p>All special methods in the dynamic API are listed in the table
below. Method names are listed in the underscore format, but their
camelCase aliases work exactly the same way.</p>
<table border="1" class="tabular docutils">
<caption>All special methods in the dynamic API</caption>
<colgroup>
<col width="27%" />
<col width="16%" />
<col width="57%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Name</th>
<th class="head">Arguments</th>
<th class="head">Purpose</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>get_keyword_names</td>
<td>&nbsp;</td>
<td>Return names of the implemented keywords.</td>
</tr>
<tr><td>run_keyword</td>
<td>name, arguments</td>
<td>Execute the specified keyword with given arguments.</td>
</tr>
<tr><td>get_keyword_arguments</td>
<td>name</td>
<td>Return keywords' argument specifications. Optional.</td>
</tr>
<tr><td>get_keyword_documentation</td>
<td>name</td>
<td>Return keywords' and library's documentation. Optional.</td>
</tr>
</tbody>
</table>
<p>It is possible to write a formal interface specification in Java, as
below. However, remember that libraries <em>do not need</em> to implement
any explicit interface, because Robot Framework directly checks with
reflection if the library has the required <span class="code">get_keyword_names</span> and
<span class="code">run_keyword</span> methods. Additionally,
<span class="code">get_keyword_arguments</span> and <span class="code">get_keyword_documentation</span>
are completely optional.</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">RobotFrameworkDynamicAPI</span> <span class="o">{</span>

    <span class="n">String</span><span class="o">[]</span> <span class="nf">getKeywordNames</span><span class="o">();</span>

    <span class="n">Object</span> <span class="nf">runKeyword</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">Object</span><span class="o">[]</span> <span class="n">arguments</span><span class="o">);</span>

    <span class="n">String</span><span class="o">[]</span> <span class="nf">getKeywordArguments</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">);</span>

    <span class="n">String</span> <span class="nf">getKeywordDocumentation</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">);</span>

<span class="o">}</span>
</pre></div>
<p>A good example of using the dynamic API is Robot Framework's own
<a class="reference internal" href="#remote-library">Remote library</a>.</p>
</div>
</div>
<div class="section" id="hybrid-library-api">
<h3><a class="toc-backref" href="#id572">4.1.7&nbsp;&nbsp;&nbsp;Hybrid library API</a></h3>
<p>The hybrid library API is, as its name implies, a hybrid between the
static API and the dynamic API. Just as with the dynamic API, it is
possible to implement a library using the hybrid API only as a class.</p>
<div class="section" id="id199">
<h4><a class="toc-backref" href="#id573">Getting keyword names</a></h4>
<p>Keyword names are got in the exactly same way as with the dynamic
API. In practice, the library needs to have the
<span class="code">get_keyword_names</span> or <span class="code">getKeywordNames</span> method returning
a list of keyword names that the library implements.</p>
</div>
<div class="section" id="id200">
<h4><a class="toc-backref" href="#id574">Running keywords</a></h4>
<p>In the hybrid API, there is no <span class="code">run_keyword</span> method for executing
keywords. Instead, Robot Framework uses reflection to find methods
implementing keywords, similarly as with the static API. A library
using the hybrid API can either have those methods implemented
directly or, more importantly, it can handle them dynamically.</p>
<p>In Python, it is easy to handle missing methods dynamically with the
<span class="code">__getattr__</span> method. This special method is probably familiar
to most Python programmers and they can immediately understand the
following example. Others may find it easier to consult <a class="reference external" href="http://docs.python.org/reference/datamodel.html#attribute-access">Python Reference
Manual</a> first.</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">somewhere</span> <span class="kn">import</span> <span class="n">external_keyword</span>

<span class="k">class</span> <span class="nc">HybridExample</span><span class="p">:</span>

    <span class="k">def</span> <span class="nf">get_keyword_names</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="p">[</span><span class="s">&#39;my_keyword&#39;</span><span class="p">,</span> <span class="s">&#39;external_keyword&#39;</span><span class="p">]</span>

    <span class="k">def</span> <span class="nf">my_keyword</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
        <span class="k">print</span> <span class="s">&quot;My Keyword called with &#39;</span><span class="si">%s</span><span class="s">&#39;&quot;</span> <span class="o">%</span> <span class="n">arg</span>

    <span class="k">def</span> <span class="nf">__getattr__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">name</span> <span class="o">==</span> <span class="s">&#39;external_keyword&#39;</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">external_keyword</span>
        <span class="k">raise</span> <span class="ne">AttributeError</span><span class="p">(</span><span class="s">&quot;Non-existing attribute &#39;</span><span class="si">%s</span><span class="s">&#39;&quot;</span> <span class="o">%</span> <span class="n">name</span><span class="p">)</span>
</pre></div>
<p>Note that <span class="code">__getattr__</span> does not execute the actual keyword like
<span class="code">run_keyword</span> does with the dynamic API. Instead, it only
returns a callable object that is then executed by Robot Framework.</p>
<p>Another point to be noted is that Robot Framework uses the same names that
are returned from <span class="code">get_keyword_names</span> for finding the methods
implementing them. Thus the names of the methods that are implemented in
the class itself must be returned in the same format as they are
defined. For example, the library above would not work correctly, if
<span class="code">get_keyword_names</span> returned <span class="code">My Keyword</span> instead of
<span class="code">my_keyword</span>.</p>
<p>The hybrid API is not very useful with Java, because it is not
possible to handle missing methods with it. Of course, it is possible
to implement all the methods in the library class, but that brings few
benefits compared to the static API.</p>
</div>
<div class="section" id="getting-keyword-arguments-and-documentation">
<h4><a class="toc-backref" href="#id575">Getting keyword arguments and documentation</a></h4>
<p>When this API is used, Robot Framework uses reflection to find the
methods implementing keywords, similarly as with the static API. After
getting a reference to the method, it searches for arguments and
documentation from it, in the same way as when using the static
API. Thus there is no need for special methods for getting arguments
and documentation like there is with the dynamic API.</p>
</div>
<div class="section" id="id202">
<h4><a class="toc-backref" href="#id576">Summary</a></h4>
<p>When implementing a test library in Python, the hybrid API has the same
dynamic capabilities as the actual dynamic API. A great benefit with it is
that there is no need to have special methods for getting keyword
arguments and documentation. It is also often practical that the only real
dynamic keywords need to be handled in <span class="code">__getattr__</span> and others
can be implemented directly in the main library class.</p>
<p>Because of the clear benefits and equal capabilities, the hybrid API
is in most cases a better alternative than the dynamic API when using
Python. One notable exception is implementing a library as a proxy for
an actual library implementation elsewhere, because then the actual
keyword must be executed elsewhere and the proxy can only pass forward
the keyword name and arguments.</p>
<p>A good example of using the hybrid API is Robot Framework's own
<a class="reference internal" href="#telnet-library">Telnet library</a>.</p>
</div>
</div>
<div class="section" id="using-robot-framework-s-internal-modules">
<h3><a class="toc-backref" href="#id577">4.1.8&nbsp;&nbsp;&nbsp;Using Robot Framework's internal modules</a></h3>
<p>Test libraries implemented with Python can use Robot Framework's
internal modules, for example, to get information about the executed
tests and the settings that are used. This powerful mechanism to
communicate with the framework should be used with care, though,
because all Robot Framework's APIs are not meant to be used by
externally and they might change radically between different framework
versions.</p>
<p>The safest API to use are methods implementing keywords in the
<a class="reference internal" href="#builtin-library">BuiltIn</a> library. Changes to keywords are rare and they are always
done so that old usage is first deprecated. One of the most useful
methods is <span class="code">replace_variables</span> which allows accessing currently
available variables. The following example demonstrates how to get
<span class="var">${OUTPUT_DIR}</span> which is one of the many handy <a class="reference internal" href="#automatic-variables">automatic
variables</a>. It is also possible to set new variables from libraries
using <span class="code">set_test_variable</span>, <span class="code">set_suite_variable</span> and
<span class="code">set_global_variable</span>.</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">os.path</span>
<span class="kn">from</span> <span class="nn">robot.libraries.BuiltIn</span> <span class="kn">import</span> <span class="n">BuiltIn</span>

<span class="k">def</span> <span class="nf">do_something</span><span class="p">(</span><span class="n">argument</span><span class="p">):</span>
    <span class="n">output</span> <span class="o">=</span> <span class="n">do_something_that_creates_a_lot_of_output</span><span class="p">(</span><span class="n">argument</span><span class="p">)</span>
    <span class="n">outputdir</span> <span class="o">=</span> <span class="n">BuiltIn</span><span class="p">()</span><span class="o">.</span><span class="n">replace_variables</span><span class="p">(</span><span class="s">&#39;${OUTPUTDIR}&#39;</span><span class="p">)</span>
    <span class="n">path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">outputdir</span><span class="p">,</span> <span class="s">&#39;results.txt&#39;</span><span class="p">)</span>
    <span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="s">&#39;w&#39;</span><span class="p">)</span>
    <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">output</span><span class="p">)</span>
    <span class="n">f</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
    <span class="k">print</span> <span class="s">&#39;*HTML* Output written to &lt;a href=&quot;results.txt&quot;&gt;results.txt&lt;/a&gt;&#39;</span>
</pre></div>
<p>The only catch with using methods from <span class="code">BuiltIn</span> is that all
<span class="code">run_keyword</span> method variants must be handled specially.
Methods that use <span class="code">run_keyword</span> methods have to be registered
as <em>run keywords</em> themselves using <span class="code">register_run_keyword</span>
method in <span class="code">BuiltIn</span> module. This method's documentation explains
why this needs to be done and obviously also how to do it.</p>
<p>The plan is to document all the internal modules better so that it is
easier to decide which can be used and how they should be used. If you
are unsure is using some API safe, please send a question to either
user or developer <a class="reference internal" href="#mailing-lists">mailing list</a>.</p>
</div>
<div class="section" id="extending-existing-test-libraries">
<h3><a class="toc-backref" href="#id578">4.1.9&nbsp;&nbsp;&nbsp;Extending existing test libraries</a></h3>
<p>This section explains different approaches how to add new
functionality to existing test libraries and how to use them in your
own libraries otherwise.</p>
<div class="section" id="modifying-original-source-code">
<h4><a class="toc-backref" href="#id579">Modifying original source code</a></h4>
<p>If you have access to the source code of the library you want to
extend, you can naturally modify the source code directly. The biggest
problem of this approach is that it can be hard for you to update the
original library without affecting your changes. For users it may also
be confusing to use a library that has different functionality than
the original one. Repackaging the library may also be a big extra
task.</p>
<p>This approach works extremely well if the enhancements are generic and
you plan to submit them back to the original developers. If your
changes are applied to the original library, they are included in the
future releases and all the problems discussed above are mitigated. If
changes are non-generic, or you for some other reason cannot submit
them back, the approaches explained in the subsequent sections
probably work better.</p>
</div>
<div class="section" id="using-inheritance">
<h4><a class="toc-backref" href="#id580">Using inheritance</a></h4>
<p>Another straightforward way to extend an existing library is using
inheritance. This is illustrated by the example below that adds new
<span class="name">Title Should Start With</span> keyword to the <a class="reference external" href="http://code.google.com/p/robotframework-seleniumlibrary">SeleniumLibrary</a>. This
example uses Python, but you can obviously extend an existing Java
library in Java code the same way.</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">SeleniumLibrary</span> <span class="kn">import</span> <span class="n">SeleniumLibrary</span>

<span class="k">class</span> <span class="nc">ExtendedSeleniumLibrary</span><span class="p">(</span><span class="n">SeleniumLibrary</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">title_should_start_with</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">expected</span><span class="p">):</span>
        <span class="n">title</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_title</span><span class="p">()</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">title</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">expected</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">AssertionError</span><span class="p">(</span><span class="s">&quot;Title &#39;</span><span class="si">%s</span><span class="s">&#39; did not start with &#39;</span><span class="si">%s</span><span class="s">&#39;&quot;</span>
                                 <span class="o">%</span> <span class="p">(</span><span class="n">title</span><span class="p">,</span> <span class="n">expected</span><span class="p">))</span>
</pre></div>
<p>A big difference with this approach compared to modifying the original
library is that the new library has a different name than the
original. A benefit is that you can easily tell that you are using a
custom library, but a big problem is that you cannot easily use the
new library with the original. First of all your new library will have
same keywords as the original meaning that there is always
<a class="reference internal" href="#handling-keywords-with-same-names">conflict</a>. Another problem is that the libraries do not share their
state.</p>
<p>This approach works well when you start to use a new library and want
to add custom enhancements to it from the beginning. Otherwise other
mechanisms explained in this section are probably better.</p>
</div>
<div class="section" id="using-other-libraries-directly">
<h4><a class="toc-backref" href="#id581">Using other libraries directly</a></h4>
<p>Because test libraries are technically just classes or modules, a
simple way to use another library is importing it and using its
methods. This approach works great when the methods are static and do
not depend on the library state. This is illustrated by the earlier
example that uses <a class="reference internal" href="#using-robot-framework-s-internal-modules">Robot Framework's BuiltIn library</a>.</p>
<p>If the library has state, however, things may not work as you would
hope.  The library instance you use in your library will not be the
same as the framework uses, and thus changes done by executed keywords
are not visible to your library. The next section explains how to get
an access to the same library instance that the framework uses.</p>
</div>
<div class="section" id="getting-active-library-instance-from-robot-framework">
<h4><a class="toc-backref" href="#id582">Getting active library instance from Robot Framework</a></h4>
<p>Robot Framework 2.5.2 added new <a class="reference internal" href="#builtin-library">BuiltIn</a> keyword <span class="name">Get Library
Instance</span> that can be used to get the currently active library
instance from the framework itself. The library instance returned by
this keyword is the same as the framework itself uses, and thus
there is no problem seeing the correct library state. Although this
functionality is available as a keyword, it is typically used in test
libraries directly by importing the <span class="name">BuiltIn</span> library class <a class="reference internal" href="#using-robot-framework-s-internal-modules">as
discussed earlier</a>. The following example illustrates how to
implement the same <span class="name">Title Should Start With</span> keyword as in the
earlier example about <a class="reference internal" href="#using-inheritance">using inheritance</a>.</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">robot.libraries.BuiltIn</span> <span class="kn">import</span> <span class="n">BuiltIn</span>

<span class="k">def</span> <span class="nf">title_should_start_with</span><span class="p">(</span><span class="n">expected</span><span class="p">):</span>
    <span class="n">seleniumlib</span> <span class="o">=</span> <span class="n">BuiltIn</span><span class="p">()</span><span class="o">.</span><span class="n">get_library_instance</span><span class="p">(</span><span class="s">&#39;SeleniumLibrary&#39;</span><span class="p">)</span>
    <span class="n">title</span> <span class="o">=</span> <span class="n">seleniumlib</span><span class="o">.</span><span class="n">get_title</span><span class="p">()</span>
    <span class="k">if</span> <span class="ow">not</span> <span class="n">title</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">expected</span><span class="p">):</span>
        <span class="k">raise</span> <span class="ne">AssertionError</span><span class="p">(</span><span class="s">&quot;Title &#39;</span><span class="si">%s</span><span class="s">&#39; did not start with &#39;</span><span class="si">%s</span><span class="s">&#39;&quot;</span>
                             <span class="o">%</span> <span class="p">(</span><span class="n">title</span><span class="p">,</span> <span class="n">expected</span><span class="p">))</span>
</pre></div>
<p>This approach is clearly better than importing the library directly
and using it when the library has a state. The biggest benefit over
inheritance is that you can use the original library normally and use
the new library in addition to it when needed. That is demonstrated in
the example below where the code from the previous examples is
expected to be available in a new library <span class="name">SeLibExtensions</span>.</p>
<table border="1" class="example docutils">
<caption>Using library and another library that extends it</caption>
<colgroup>
<col width="28%" />
<col width="38%" />
<col width="18%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Settings</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>SeleniumLibrary</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Library</td>
<td>SeLibExtensions</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<table border="1" class="example docutils">
<colgroup>
<col width="22%" />
<col width="33%" />
<col width="20%" />
<col width="25%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Test Case</th>
<th class="head">Action</th>
<th class="head">Argument</th>
<th class="head">Argument</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Example</td>
<td>Open Browser</td>
<td><a class="reference external" href="http://example">http://example</a></td>
<td># SeleniumLibrary</td>
</tr>
<tr><td></td>
<td>Title Should Start With</td>
<td>Example</td>
<td># SeLibExtensions</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="libraries-using-dynamic-or-hybrid-api">
<h4><a class="toc-backref" href="#id583">Libraries using dynamic or hybrid API</a></h4>
<p>Test libraries that use the <a class="reference internal" href="#dynamic-library-api">dynamic</a> or <a class="reference internal" href="#hybrid-library-api">hybrid library API</a> often
have their own systems how to extend them. With these libraries you
need to ask guidance from the library developers or consult the
library documentation or source code.</p>
</div>
</div>
</div>
<div class="section" id="remote-library-interface">
<h2><a class="toc-backref" href="#id532">4.2&nbsp;&nbsp;&nbsp;Remote library interface</a></h2>
<p>The remote library interface provides means for having test libraries
on different machines than where Robot Framework itself is running,
and also for implementing libraries using other languages than the
natively supported Python and Java. For a test library user remote
libraries look pretty much the same as any other test library, and
developing test libraries using the remote library interface is also
very close to creating <a class="reference internal" href="#creating-test-libraries">normal test libraries</a>.</p>
<div class="contents local topic" id="id208">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#id209" id="id584">4.2.1&nbsp;&nbsp;&nbsp;Introduction</a></li>
<li><a class="reference internal" href="#taking-remote-library-into-use" id="id585">4.2.2&nbsp;&nbsp;&nbsp;Taking Remote library into use</a><ul>
<li><a class="reference internal" href="#importing-remote-library" id="id586">Importing Remote library</a></li>
<li><a class="reference internal" href="#starting-and-stopping-remote-servers" id="id587">Starting and stopping remote servers</a></li>
</ul>
</li>
<li><a class="reference internal" href="#supported-argument-and-return-value-types" id="id588">4.2.3&nbsp;&nbsp;&nbsp;Supported argument and return value types</a></li>
<li><a class="reference internal" href="#using-remote-servers" id="id589">4.2.4&nbsp;&nbsp;&nbsp;Using remote servers</a><ul>
<li><a class="reference internal" href="#python-remote-library-example" id="id590">Python remote library example</a></li>
<li><a class="reference internal" href="#ruby-remote-library-example" id="id591">Ruby remote library example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#remote-protocol" id="id592">4.2.5&nbsp;&nbsp;&nbsp;Remote protocol</a><ul>
<li><a class="reference internal" href="#required-methods" id="id593">Required methods</a></li>
<li><a class="reference internal" href="#getting-remote-keyword-names-and-other-information" id="id594">Getting remote keyword names and other information</a></li>
<li><a class="reference internal" href="#executing-remote-keywords" id="id595">Executing remote keywords</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="id209">
<h3><a class="toc-backref" href="#id584">4.2.1&nbsp;&nbsp;&nbsp;Introduction</a></h3>
<p>There are two main reasons for using the remote library API:</p>
<ul class="simple">
<li>It is possible to have actual libraries on different machines than
where Robot Framework is running. This allows interesting
possibilities for distributed testing.</li>
<li>Test libraries can be implemented using any language that supports
<a class="reference external" href="http://www.xmlrpc.com/">XML-RPC</a> protocol. Robot Framework 2.1 contains generic <a class="reference internal" href="#using-remote-servers">remote
servers</a> for Python/Jython and Ruby, and the plan is to implement
generic servers for other languages like Java and Perl in the future.</li>
</ul>
<p>The remote library interface is provided by the Remote library that is
one of the <a class="reference internal" href="#standard-libraries">standard libraries</a> starting from Robot Framework
2.1. This library does not have any keywords of its own, but it works
as a proxy between the core framework and keywords implemented
elsewhere. The Remote library interacts with actual library
implementations through <a class="reference internal" href="#using-remote-servers">remote servers</a>, and the Remote library and
servers communicate using a simple <a class="reference internal" href="#remote-protocol">remote protocol</a> on top of an
XML-RPC channel.  The high level architecture of all this is
illustrated in the picture below:</p>
<div class="figure">
<img alt="src/ExtendingRobotFramework/remote.png" src="src/ExtendingRobotFramework/remote.png" />
<p class="caption">Robot Framework architecture with Remote library</p>
</div>
</div>
<div class="section" id="taking-remote-library-into-use">
<h3><a class="toc-backref" href="#id585">4.2.2&nbsp;&nbsp;&nbsp;Taking Remote library into use</a></h3>
<div class="section" id="importing-remote-library">
<h4><a class="toc-backref" href="#id586">Importing Remote library</a></h4>
<p>The Remote library needs to know the address of the remote server but
otherwise importing it and using keywords that it provides is no
different to how other libraries are used. If you need to use the Remote
library multiple times in a test suite, or just want to give it a more
descriptive name, you can import it using the <a class="reference internal" href="#setting-custom-name-to-test-library">WITH NAME syntax</a>.</p>
<table border="1" class="example docutils">
<caption>Importing Remote library</caption>
<colgroup>
<col width="15%" />
<col width="18%" />
<col width="37%" />
<col width="15%" />
<col width="15%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Setting</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>Remote</td>
<td>http://localhost:8270</td>
<td>WITH NAME</td>
<td>Example1</td>
</tr>
<tr><td>Library</td>
<td>Remote</td>
<td>http://10.0.0.42:7777</td>
<td>WITH NAME</td>
<td>Example2</td>
</tr>
</tbody>
</table>
<p>The URL used by the first example above is also the default address
that the Remote library uses if no address is given. Similarly port
<span class="code">8270</span> is the default port the provided remote servers use. (82
and 70 are the ASCII codes of letters <cite>R</cite> and <cite>F</cite>, respectively.)</p>
</div>
<div class="section" id="starting-and-stopping-remote-servers">
<h4><a class="toc-backref" href="#id587">Starting and stopping remote servers</a></h4>
<p>Before the Remote library can be imported, the remote server providing
the actual keywords must be started.  If the server is started before
launching the test execution, it is possible to use the normal
<span class="opt">Library</span> setting like in the above example. Alternatively other
keywords, for example from OperatingSystem or SSH libraries, can start
the server up, but then you may need to use <a class="reference internal" href="#using-import-library-keyword">Import Library keyword</a>
because the library is not available when the test execution starts.</p>
<p>How a remote server can be stopped depends on how it is
implemented. Following methods work with the servers distributed with
Robot Framework:</p>
<ul class="simple">
<li>Regardless of the library used, remote servers provide <span class="name">Stop
Remote Server</span> keyword that can be used from the test data.</li>
<li>Remote servers have <span class="code">stop_remote_server</span> method in their
XML-RPC interface.</li>
<li><span class="code">Ctrl-C</span> stops the server if it is running on a terminal
window. Unfortunately this does not work with all servers on all
operating systems.</li>
<li>The server process can be terminated using tools provided by the
operating system (e.g. <span class="prog">kill</span>).</li>
</ul>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The server may be configured so that users cannot stop it with
<span class="name">Stop Remote Server</span> keyword or <span class="code">stop_remote_server</span>
method.</p>
</div>
</div>
</div>
<div class="section" id="supported-argument-and-return-value-types">
<h3><a class="toc-backref" href="#id588">4.2.3&nbsp;&nbsp;&nbsp;Supported argument and return value types</a></h3>
<p>Because the XML-RPC protocol does not support all possible object
types, the values transferred between the Remote library and remote
servers must be converted to compatible types. This applies to the
keyword arguments the Remote library passes to remote servers and to
the return values servers give back to the Remote library.</p>
<p>The conversions are done using following rules:</p>
<ul class="simple">
<li>Strings, numbers and Boolean values are passed without modifications.</li>
<li>The <span class="code">None/nil</span> value is converted to an empty string.</li>
<li>Lists (and tuples in Python) are passed as lists so that their contents
are converted recursively.</li>
<li>Dictionaries/maps are passed so that their values are converted
to supported types recursively and keys are converted to strings.</li>
<li>Other types are converted to strings.</li>
</ul>
</div>
<div class="section" id="using-remote-servers">
<h3><a class="toc-backref" href="#id589">4.2.4&nbsp;&nbsp;&nbsp;Using remote servers</a></h3>
<p>Robot Framework 2.1 includes remote server implementations written
both in Python and Ruby. These servers, as well as the example
libraries shown below and an example test case file, are
included in source distributions under <span class="path">tools/remoteserver</span>
directory and available also at
<a class="reference external" href="http://code.google.com/p/robotframework/wiki/RemoteLibrary">http://code.google.com/p/robotframework/wiki/RemoteLibrary</a>.</p>
<p>The provided servers are designed so that it is easy to create test
libraries using them. With both of the servers the basic procedure is
as follows:</p>
<ul class="simple">
<li>Create a test library module or class similarly as a normal test
library using the <a class="reference internal" href="#creating-static-keywords">static library API</a>. With the Python server it
is also possible to use the <a class="reference internal" href="#hybrid-library-api">hybrid library API</a>.</li>
<li>Import the remote server class and create an instance of it giving
the library instance or module to it as an argument. The listening
address and port, possibly got from the command line, can be given
as optional arguments.</li>
</ul>
<p>Both these steps can be done in the same module as illustrated by the
examples below. Executing these modules as scripts from the command
line will start the remote server so that it serves the keywords
implemented in the library.</p>
<div class="section" id="python-remote-library-example">
<h4><a class="toc-backref" href="#id590">Python remote library example</a></h4>
<p>This example demonstrates how to use the Python version of the
remote server. The example library implements keywords <span class="name">Count
Items In Directory</span> and <span class="name">Strings Should Be Equal</span>.</p>
<div class="highlight"><pre><span class="c">#!/usr/bin/env python</span>

<span class="kn">import</span> <span class="nn">os</span>
<span class="kn">import</span> <span class="nn">sys</span>


<span class="k">class</span> <span class="nc">ExampleRemoteLibrary</span><span class="p">:</span>
    <span class="sd">&quot;&quot;&quot;Example library to be used with Robot Framework&#39;s remote server.</span>

<span class="sd">    This documentation is visible in docs generated by _libdoc.py_</span>
<span class="sd">    starting from Robot Framework 2.6.2.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;Also this doc should be in shown in library doc.&quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="nf">count_items_in_directory</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">path</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;Returns the number of items in the directory specified by `path`.&quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="nb">len</span><span class="p">([</span><span class="n">i</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">listdir</span><span class="p">(</span><span class="n">path</span><span class="p">)</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">i</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s">&#39;.&#39;</span><span class="p">)])</span>

    <span class="k">def</span> <span class="nf">strings_should_be_equal</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">str1</span><span class="p">,</span> <span class="n">str2</span><span class="p">):</span>
        <span class="k">print</span> <span class="s">&quot;Comparing &#39;</span><span class="si">%s</span><span class="s">&#39; to &#39;</span><span class="si">%s</span><span class="s">&#39;&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">str1</span><span class="p">,</span> <span class="n">str2</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">str1</span> <span class="o">!=</span> <span class="n">str2</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">AssertionError</span><span class="p">(</span><span class="s">&quot;Given strings are not equal&quot;</span><span class="p">)</span>


<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">&#39;__main__&#39;</span><span class="p">:</span>
    <span class="kn">from</span> <span class="nn">robotremoteserver</span> <span class="kn">import</span> <span class="n">RobotRemoteServer</span>
    <span class="n">RobotRemoteServer</span><span class="p">(</span><span class="n">ExampleRemoteLibrary</span><span class="p">(),</span> <span class="o">*</span><span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">:])</span>
</pre></div>
</div>
<div class="section" id="ruby-remote-library-example">
<h4><a class="toc-backref" href="#id591">Ruby remote library example</a></h4>
<p>This example uses the Ruby remote server and provides exactly same
keywords as the previous Python example:</p>
<div class="highlight"><pre><span class="c1">#!/usr/bin/env ruby</span>

<span class="k">class</span> <span class="nc">ExampleRemoteLibrary</span>

  <span class="k">def</span> <span class="nf">count_items_in_directory</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
    <span class="no">Dir</span><span class="o">.</span><span class="n">entries</span><span class="p">(</span><span class="n">path</span><span class="p">)</span><span class="o">.</span><span class="n">find_all</span><span class="p">{</span><span class="o">|</span><span class="n">i</span><span class="o">|</span> <span class="ow">not</span> <span class="n">i</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="s1">&#39;^\.&#39;</span><span class="p">)}</span><span class="o">.</span><span class="n">length</span>
  <span class="k">end</span> 

  <span class="k">def</span> <span class="nf">strings_should_be_equal</span><span class="p">(</span><span class="n">str1</span><span class="p">,</span> <span class="n">str2</span><span class="p">)</span>
    <span class="nb">puts</span> <span class="s2">&quot;Comparing &#39;</span><span class="si">#{</span><span class="n">str1</span><span class="si">}</span><span class="s2">&#39; to &#39;</span><span class="si">#{</span><span class="n">str2</span><span class="si">}</span><span class="s2">&#39;&quot;</span>
    <span class="k">if</span> <span class="n">str1</span> <span class="o">!=</span> <span class="n">str2</span>
      <span class="k">raise</span> <span class="no">RuntimeError</span><span class="p">,</span> <span class="s2">&quot;Given strings are not equal&quot;</span>
    <span class="k">end</span>
  <span class="k">end</span>

<span class="k">end</span>


<span class="k">if</span> <span class="bp">__FILE__</span> <span class="o">==</span> <span class="vg">$0</span>
  <span class="nb">require</span> <span class="s2">&quot;robotremoteserver&quot;</span>
  <span class="no">RobotRemoteServer</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="no">ExampleRemoteLibrary</span><span class="o">.</span><span class="n">new</span><span class="p">,</span> <span class="o">*</span><span class="no">ARGV</span><span class="p">)</span>
<span class="k">end</span>
</pre></div>
</div>
</div>
<div class="section" id="remote-protocol">
<h3><a class="toc-backref" href="#id592">4.2.5&nbsp;&nbsp;&nbsp;Remote protocol</a></h3>
<p>This section explains the protocol that is used between the Remote
library and remote servers. This information is mainly targeted for
people who want to create new remote servers. The provided Python and
Ruby servers can also be used as examples.</p>
<p>The remote protocol is implemented on top of <a class="reference external" href="http://www.xmlrpc.com/">XML-RPC</a>, which is a
simple remote procedure call protocol using XML over HTTP. Most
mainstream languages (Python, Java, C, Ruby, Perl, Javascript, PHP,
...) have a support for XML-RPC either built-in or as extensions.</p>
<div class="section" id="required-methods">
<h4><a class="toc-backref" href="#id593">Required methods</a></h4>
<p>A remote server is an XML-RPC server that must have the same methods
in its public interface as the <a class="reference internal" href="#dynamic-library-api">dynamic library API</a> has. Only
<span class="code">get_keyword_names</span> and <span class="code">run_keyword</span> are actually
required, but <span class="code">get_keyword_arguments</span> and
<span class="code">get_keyword_documentation</span> are also recommended. Notice that
using camelCase format in method names is not possible currently. How
the actual keywords are implemented is not relevant for the Remote
library.  A remote server can either act as a wrapper for real test
libraries, like the provided Python and Ruby servers do, or it can
implement keywords itself.</p>
<p>Remote servers should additionally have <span class="code">stop_remote_server</span>
method in their public interface to ease stopping them. They should
also expose this method as <span class="name">Stop Remote Server</span> keyword
automatically so that it can be used in the test data regardless of
the test library. Allowing users to stop the server using these
methods is not always desirable, and servers can choose to allow
disabling them via some configuration parameter.</p>
<p>The provided Python remote server can be used as a reference
implementation.</p>
</div>
<div class="section" id="getting-remote-keyword-names-and-other-information">
<h4><a class="toc-backref" href="#id594">Getting remote keyword names and other information</a></h4>
<p>The Remote library gets a list of keywords that the remote server
provides using <span class="code">get_keyword_names</span> method. This method must
return the keyword names as a list of strings.</p>
<p>Remote servers can, and should, also implement
<span class="code">get_keyword_arguments</span> and <span class="code">get_keyword_documentation</span>
methods to provide more information about the keywords. Both of these
keywords get the name of the keyword as an argument. Arguments must be
returned as a list of strings in the <a class="reference internal" href="#getting-keyword-arguments">same format as with dynamic
libraries</a>, and documentation must be returned <a class="reference internal" href="#getting-keyword-documentation">as a string</a>.</p>
<p>Starting from Robot Framework 2.6.2, remote servers can also provide
<a class="reference internal" href="#getting-general-library-documentation">general library documentation</a> to be used when generating
documenation with <a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> tool.</p>
</div>
<div class="section" id="executing-remote-keywords">
<h4><a class="toc-backref" href="#id595">Executing remote keywords</a></h4>
<p>When the Remote library wants the server to execute some keyword, it
calls remote server's <span class="code">run_keyword</span> method and passes it the
keyword name and a list of arguments. Base types can be used as
arguments directly but more complex types are <a class="reference internal" href="#supported-argument-and-return-value-types">converted to supported
types</a>.</p>
<p>The server must return results of the execution in a result dictionary
(or map, depending on terminology) containing items explained in the
following table.</p>
<table border="1" class="tabular docutils">
<caption>Entries in the remote result dictionary</caption>
<colgroup>
<col width="18%" />
<col width="82%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Name</th>
<th class="head">Explanation</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>status</td>
<td>Mandatory execution status. Either PASS or FAIL.</td>
</tr>
<tr><td>output</td>
<td>Possible output to write into the log file. Must be
given as a single string but can contain multiple
messages and different <a class="reference internal" href="#logging-information">log levels</a> in format
<span class="msg">*INFO* First message\n*INFO* Second\n*WARN*
Another message</span>.</td>
</tr>
<tr><td>return</td>
<td>Possible return value. Must be one of the <a class="reference internal" href="#supported-argument-and-return-value-types">supported
types</a>.</td>
</tr>
<tr><td>error</td>
<td>Possible error message. Used only when the execution
fails.</td>
</tr>
<tr><td>traceback</td>
<td>Possible stack trace to <a class="reference internal" href="#reporting-keyword-status">write into the log file</a>
using DEBUG level when the execution fails.</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="section" id="using-listener-interface">
<h2><a class="toc-backref" href="#id533">4.3&nbsp;&nbsp;&nbsp;Using listener interface</a></h2>
<p>Robot Framework has a listener interface that can be used to receive
notifications about test execution. Listeners are classes or modules
with certain special methods, and they can be implemented both with
Python and Java. Example uses of the listener interface include
external test monitors, sending a mail message when a test fails, and
communicating with other systems.</p>
<div class="contents local topic" id="id218">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#taking-listeners-into-use" id="id596">4.3.1&nbsp;&nbsp;&nbsp;Taking listeners into use</a></li>
<li><a class="reference internal" href="#available-listener-interface-methods" id="id597">4.3.2&nbsp;&nbsp;&nbsp;Available listener interface methods</a><ul>
<li><a class="reference internal" href="#listener-interface-versions" id="id598">Listener interface versions</a></li>
<li><a class="reference internal" href="#listener-interface-method-signatures" id="id599">Listener interface method signatures</a></li>
</ul>
</li>
<li><a class="reference internal" href="#listeners-logging" id="id600">4.3.3&nbsp;&nbsp;&nbsp;Listeners logging</a></li>
<li><a class="reference internal" href="#listener-examples" id="id601">4.3.4&nbsp;&nbsp;&nbsp;Listener examples</a></li>
</ul>
</div>
<div class="section" id="taking-listeners-into-use">
<h3><a class="toc-backref" href="#id596">4.3.1&nbsp;&nbsp;&nbsp;Taking listeners into use</a></h3>
<p>Listeners are taken into use from the command line with the <span class="opt">--listener</span>
option, so that the name of the listener is given to it as an argument. The
listener name is got from the name of the class or module implementing the
listener interface, similarly as <a class="reference internal" href="#test-library-names">test library names</a> are got from classes
implementing them. The specified listeners must be in the same <a class="reference internal" href="#adjusting-library-search-path">module search
path</a> where test libraries are searched from when they are imported. Other
option is to give an absolute or a relative path to the listener file
<a class="reference internal" href="#using-physical-path-to-library">similarly as with test libraries</a>. It is possible to take multiple listeners
into use by using this option several times.</p>
<p>It is also possible to give arguments to listener classes from the
command line. Arguments are specified after the listener name (or
path) using a colon as a separator. This approach provides only string
type arguments and arguments obviously cannot contain colons. However,
it should be pretty easy to listeners to go around these limitations.</p>
<p>Examples:</p>
<pre class="literal-block">
pybot --listener MyListener tests.html
jybot --listener com.company.package.Listener tests.html
pybot --listener path/to/MyListener.py tests.html
pybot --listener module.Listener --listener AnotherListener tests.html
pybot --listener ListenerWithArgs:arg1:arg2
pybot --listener path/to/MyListener.java:argument tests.html
</pre>
</div>
<div class="section" id="available-listener-interface-methods">
<h3><a class="toc-backref" href="#id597">4.3.2&nbsp;&nbsp;&nbsp;Available listener interface methods</a></h3>
<p>Robot Framework creates an instance of the listener class with given arguments
when test execution starts. During the test execution, Robot Framework calls
listeners' methods when test suites, test cases and keywords start and end. It
also calls the appropriate methods when output files are ready, and finally at
the end it calls the <span class="code">close</span> method. A listener is not required to
implement any official interface, and it only needs to have the methods it
actually needs.</p>
<div class="section" id="listener-interface-versions">
<h4><a class="toc-backref" href="#id598">Listener interface versions</a></h4>
<p>The signatures of methods related to test execution progress were changed in
Robot Framework 2.1. This change was made so that new information can be added
to listener interface without breaking existing listeners. The old signatures
will continue to work, but they will be deprecated in some future version, so
all new listeners should be implemented with signatures described in the table
below. The most recent detailed description of the old listener interface can
be found in User Guide of Robot Framework 2.0.4.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">A listener must have attribute <span class="code">ROBOT_LISTENER_API_VERSION</span>
defined in order to be recognized as a new style listener. Value of the
<span class="code">ROBOT_LISTENER_API_VERSION</span> attribute must be 2, either as a string or
as an integer. The examples below are implemented as new style listeners.</p>
</div>
</div>
<div class="section" id="listener-interface-method-signatures">
<h4><a class="toc-backref" href="#id599">Listener interface method signatures</a></h4>
<p>All listener methods related to test execution progress have the same
signature <span class="code">method(name, attributes)</span>, where <span class="code">attributes</span>
is a dictionary containing details of the event. The following table
lists all the available methods in the listener interface and the
contents of the <span class="code">attributes</span> dictionary, where applicable. Keys
of the dictionary are strings. All of these methods have also
<cite>camelCase</cite> aliases.  Thus, for example, <span class="code">startSuite</span> is a
synonym to <span class="code">start_suite</span>.</p>
<table border="1" class="tabular docutils">
<caption>Available methods in the listener interface</caption>
<colgroup>
<col width="18%" />
<col width="22%" />
<col width="60%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Method</th>
<th class="head">Arguments</th>
<th class="head">Attributes / Explanation</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>start_suite</td>
<td>name, attributes</td>
<td><p class="first">Keys in the attribute dictionary:</p>
<ul class="last simple">
<li>longname: suite name including parent suites</li>
<li>doc: test suite documentation</li>
<li>metadata: dictionary/map containing <a class="reference internal" href="#free-test-suite-metadata">free test
suite metadata</a> (new in 2.5)</li>
<li>source: absolute path of the file/directory
test suite was created from (new in 2.7)</li>
<li>suites: names of suites directly in this suite
as a list of strings (new in 2.5)</li>
<li>tests: names of tests directly in this suite
as a list of strings (new in 2.5)</li>
<li>totaltests: total number of tests in this suite
and all its sub-suites as an integer (new in
2.5)</li>
<li>starttime: execution start time</li>
</ul>
</td>
</tr>
<tr><td>end_suite</td>
<td>name, attributes</td>
<td><p class="first">Keys in the attribute dictionary:</p>
<ul class="last simple">
<li>longname: test suite name including parents</li>
<li>doc: test suite documentation</li>
<li>metadata: dictionary/map containing <a class="reference internal" href="#free-test-suite-metadata">free test
suite metadata</a> (new in 2.6)</li>
<li>source: absolute path of the file/directory
test suite was created from (new in 2.7)</li>
<li>starttime: execution start time</li>
<li>endtime: execution end time</li>
<li>elapsedtime: execution time in milliseconds
as an integer</li>
<li>status: either <span class="code">PASS</span> or <span class="code">FAIL</span></li>
<li>statistics: suite statistics (number of passed
and failed tests in the suite) as a string</li>
<li>message: error message if the suite setup or
teardown has failed, empty otherwise</li>
</ul>
</td>
</tr>
<tr><td>start_test</td>
<td>name, attributes</td>
<td><p class="first">Keys in the attribute dictionary:</p>
<ul class="last simple">
<li>longname: test name including parent suites</li>
<li>doc: test case documentation</li>
<li>tags: test case tags as a list of strings</li>
<li>critical: <span class="code">yes</span> or <span class="code">no</span> depending
is test considered critical or not (new in 2.6)</li>
<li>template: contains the name of the template
used for the test. If the test is not templated
it will be an empty string (new in 2.6)</li>
<li>starttime: execution start time</li>
</ul>
</td>
</tr>
<tr><td>end_test</td>
<td>name, attributes</td>
<td><p class="first">Keys in the attribute dictionary:</p>
<ul class="last simple">
<li>longname: test name including parent suites</li>
<li>doc: test case documentation</li>
<li>tags: test case tags as a list of strings</li>
<li>critical: <span class="code">yes</span> or <span class="code">no</span> depending
is test considered critical or not (new in 2.6)</li>
<li>template: contains the name of the template
used for the test. If the test is not templated
it will be an empty string (new in 2.6)</li>
<li>starttime: execution start time</li>
<li>endtime: execution end time</li>
<li>elapsedtime: execution time in milliseconds
as an integer</li>
<li>status: either <span class="code">PASS</span> or <span class="code">FAIL</span></li>
<li>message: status message, normally an error
message or an empty string</li>
</ul>
</td>
</tr>
<tr><td>start_keyword</td>
<td>name, attributes</td>
<td><p class="first">Keys in the attribute dictionary:</p>
<ul class="last simple">
<li>type: string <span class="code">Keyword</span> for normal
keywords and <span class="code">Test Setup</span>, <span class="code">Test
Teardown</span>, <span class="code">Suite Setup</span> or <span class="code">Suite
Teardown</span> for keywords used in suite/test
setup/teardown (new in 2.6)</li>
<li>doc: keyword documentation</li>
<li>args: keyword's arguments as a list of strings</li>
<li>starttime: execution start time</li>
</ul>
</td>
</tr>
<tr><td>end_keyword</td>
<td>name, attributes</td>
<td><p class="first">Keys in the attribute dictionary:</p>
<ul class="last simple">
<li>type: same as with <span class="code">start_keyword</span></li>
<li>doc: keyword documentation</li>
<li>args: keyword's arguments as a list of strings</li>
<li>starttime: execution start time</li>
<li>endtime: execution end time</li>
<li>elapsedtime: execution time in milliseconds
as an integer</li>
<li>status: either <span class="code">PASS</span> or <span class="code">FAIL</span></li>
</ul>
</td>
</tr>
<tr><td>log_message</td>
<td>message</td>
<td><p class="first">Called when an executed keyword writes a log
message. <span class="code">message</span> is a dictionary with
the following keys:</p>
<ul class="last simple">
<li>message: the content of the message</li>
<li>level: <a class="reference internal" href="#log-levels">log level</a> used in logging the message</li>
<li>timestamp: message creation time, format is
<span class="code">YYYY-MM-DD hh:mm:ss.mil</span></li>
<li>html: string <span class="code">yes</span> or <span class="code">no</span> denoting
whether the message should be interpreted as
HTML or not</li>
</ul>
</td>
</tr>
<tr><td>message</td>
<td>message</td>
<td>Called when the framework itself writes a <a class="reference internal" href="#system-log">syslog</a>
message. <span class="code">message</span> is a dictionary with
same keys as with <span class="code">log_message</span> method.</td>
</tr>
<tr><td>output_file</td>
<td>path</td>
<td>Called when writing to an output file is
finished. The path is an absolute path to the
file.</td>
</tr>
<tr><td>log_file</td>
<td>path</td>
<td>Called when writing to a log file is
finished. The path is an absolute path to the
file.</td>
</tr>
<tr><td>report_file</td>
<td>path</td>
<td>Called when writing to a report file is
finished. The path is an absolute path to the
file.</td>
</tr>
<tr><td>debug_file</td>
<td>path</td>
<td>Called when writing to a debug file is
finished. The path is an absolute path to the
file.</td>
</tr>
<tr><td>close</td>
<td>&nbsp;</td>
<td>Called after all test suites, and test cases in
them, have been executed.</td>
</tr>
</tbody>
</table>
<p>The available methods and their arguments are also shown in a formal Java
interface specification below. Contents of the <span class="code">java.util.Map attributes</span> are
as in the table above.  It should be remembered that a listener <em>does not</em> need
to implement any explicit interface or have all these methods.</p>
<div class="highlight"><pre><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">RobotListenerInterface</span> <span class="o">{</span>
    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="kt">int</span> <span class="n">ROBOT_LISTENER_API_VERSION</span> <span class="o">=</span> <span class="mi">2</span><span class="o">;</span>
    <span class="kt">void</span> <span class="nf">startSuite</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">Map</span> <span class="n">attributes</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">endSuite</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">Map</span> <span class="n">attributes</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">startTest</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">Map</span> <span class="n">attributes</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">endTest</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">Map</span> <span class="n">attributes</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">startKeyword</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">Map</span> <span class="n">attributes</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">endKeyword</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">Map</span> <span class="n">attributes</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">logMessage</span><span class="o">(</span><span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">Map</span> <span class="n">message</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">message</span><span class="o">(</span><span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">Map</span> <span class="n">message</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">outputFile</span><span class="o">(</span><span class="n">String</span> <span class="n">path</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">logFile</span><span class="o">(</span><span class="n">String</span> <span class="n">path</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">reportFile</span><span class="o">(</span><span class="n">String</span> <span class="n">path</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">debugFile</span><span class="o">(</span><span class="n">String</span> <span class="n">path</span><span class="o">);</span>
    <span class="kt">void</span> <span class="nf">close</span><span class="o">();</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="listeners-logging">
<h3><a class="toc-backref" href="#id600">4.3.3&nbsp;&nbsp;&nbsp;Listeners logging</a></h3>
<p>Robot Framework 2.6 introduced new <a class="reference internal" href="#programmatic-logging-apis">programmatic logging APIs</a> that
also listeners can utilize. There are some limitations, however, and
how different listener methods can log messages is explained in the
table below.</p>
<table border="1" class="tabular docutils">
<caption>How listener methods can log</caption>
<colgroup>
<col width="30%" />
<col width="70%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Methods</th>
<th class="head">Explanation</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>start_keyword,
end_keyword,
log_message</td>
<td>Messages are logged to the normal <a class="reference internal" href="#log-file">log file</a>
under the executed keyword.</td>
</tr>
<tr><td>start_suite,
end_suite,
start_test, end_test</td>
<td>Messages are logged to the <a class="reference internal" href="#system-log">syslog</a>. Warnings are
shown also in the <a class="reference internal" href="#errors-and-warnings-during-execution">execution errors</a> section of
the normal log file.</td>
</tr>
<tr><td>message</td>
<td>Messages are normally logged to the syslog. If
this method is used while a keyword is executing,
messages are logged to the normal log file.</td>
</tr>
<tr><td>Other methods</td>
<td>Messages are only logged to the syslog.</td>
</tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">To avoid recursion, messages logged by listeners are not sent to
listener methods <span class="code">log_message</span> and <span class="code">message</span>.</p>
</div>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">There were severe problems with listeners logging prior
to Robot Framework 2.6.2. Using this functionality with
earlier versions is thus not recommended.</p>
</div>
</div>
<div class="section" id="listener-examples">
<h3><a class="toc-backref" href="#id601">4.3.4&nbsp;&nbsp;&nbsp;Listener examples</a></h3>
<p>The first simple example is implemented in a Python module. It mainly
illustrates that using the listener interface is not very complicated.</p>
<div class="highlight"><pre><span class="n">ROBOT_LISTENER_API_VERSION</span> <span class="o">=</span> <span class="mi">2</span>

<span class="k">def</span> <span class="nf">start_test</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">attrs</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&#39;Executing test </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">name</span>

<span class="k">def</span> <span class="nf">start_keyword</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">attrs</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&#39;Executing keyword </span><span class="si">%s</span><span class="s"> with arguments </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">attrs</span><span class="p">[</span><span class="s">&#39;args&#39;</span><span class="p">])</span>

<span class="k">def</span> <span class="nf">log_file</span><span class="p">(</span><span class="n">path</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&#39;Test log available at </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">path</span>

<span class="k">def</span> <span class="nf">close</span><span class="p">():</span>
    <span class="k">print</span> <span class="s">&#39;All tests executed&#39;</span>
</pre></div>
<p>The second example, which still uses Python, is slightly more complicated. It
writes all the information it gets into a text file in a temporary directory
without much formatting. The filename may be given from the command line, but
also has a default value. Note that in real usage, the <a class="reference internal" href="#debug-file">debug file</a>
functionality available through the command line option <span class="opt">--debugfile</span> is
probably more useful than this example.</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">os.path</span>
<span class="kn">import</span> <span class="nn">tempfile</span>


<span class="k">class</span> <span class="nc">PythonListener</span><span class="p">:</span>

    <span class="n">ROBOT_LISTENER_API_VERSION</span> <span class="o">=</span> <span class="mi">2</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s">&#39;listen.txt&#39;</span><span class="p">):</span>
        <span class="n">outpath</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">tempfile</span><span class="o">.</span><span class="n">gettempdir</span><span class="p">(),</span> <span class="n">filename</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">outfile</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">outpath</span><span class="p">,</span> <span class="s">&#39;w&#39;</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">start_suite</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">attrs</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">outfile</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;</span><span class="si">%s</span><span class="s"> &#39;</span><span class="si">%s</span><span class="s">&#39;</span><span class="se">\n</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">attrs</span><span class="p">[</span><span class="s">&#39;doc&#39;</span><span class="p">]))</span>

    <span class="k">def</span> <span class="nf">start_test</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">attrs</span><span class="p">):</span>
        <span class="n">tags</span> <span class="o">=</span> <span class="s">&#39; &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">attrs</span><span class="p">[</span><span class="s">&#39;tags&#39;</span><span class="p">])</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">outfile</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;- </span><span class="si">%s</span><span class="s"> &#39;</span><span class="si">%s</span><span class="s">&#39; [ </span><span class="si">%s</span><span class="s"> ] :: &quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">attrs</span><span class="p">[</span><span class="s">&#39;doc&#39;</span><span class="p">],</span> <span class="n">tags</span><span class="p">))</span>

    <span class="k">def</span> <span class="nf">end_test</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">attrs</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">attrs</span><span class="p">[</span><span class="s">&#39;status&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s">&#39;PASS&#39;</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">outfile</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;PASS</span><span class="se">\n</span><span class="s">&#39;</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">outfile</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;FAIL: </span><span class="si">%s</span><span class="se">\n</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">attrs</span><span class="p">[</span><span class="s">&#39;message&#39;</span><span class="p">])</span>

     <span class="k">def</span> <span class="nf">end_suite</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">attrs</span><span class="p">):</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">outfile</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;</span><span class="si">%s</span><span class="se">\n</span><span class="si">%s</span><span class="se">\n</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">attrs</span><span class="p">[</span><span class="s">&#39;status&#39;</span><span class="p">],</span> <span class="n">attrs</span><span class="p">[</span><span class="s">&#39;message&#39;</span><span class="p">]))</span>

     <span class="k">def</span> <span class="nf">close</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">outfile</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
<p>The third example implements the same functionality as the previous one, but uses Java instead of Python.</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">java.io.*</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">java.util.Map</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">java.util.List</span><span class="o">;</span>


<span class="kd">public</span> <span class="kd">class</span> <span class="nc">JavaListener</span> <span class="o">{</span>

    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="kt">int</span> <span class="n">ROBOT_LISTENER_API_VERSION</span> <span class="o">=</span> <span class="mi">2</span><span class="o">;</span>
    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="n">String</span> <span class="n">DEFAULT_FILENAME</span> <span class="o">=</span> <span class="s">&quot;listen_java.txt&quot;</span><span class="o">;</span>
    <span class="kd">private</span> <span class="n">BufferedWriter</span> <span class="n">outfile</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span>

    <span class="kd">public</span> <span class="nf">JavaListener</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span>
        <span class="k">this</span><span class="o">(</span><span class="n">DEFAULT_FILENAME</span><span class="o">);</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="nf">JavaListener</span><span class="o">(</span><span class="n">String</span> <span class="n">filename</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span>
        <span class="n">String</span> <span class="n">tmpdir</span> <span class="o">=</span> <span class="n">System</span><span class="o">.</span><span class="na">getProperty</span><span class="o">(</span><span class="s">&quot;java.io.tmpdir&quot;</span><span class="o">);</span>
        <span class="n">String</span> <span class="n">sep</span> <span class="o">=</span> <span class="n">System</span><span class="o">.</span><span class="na">getProperty</span><span class="o">(</span><span class="s">&quot;file.separator&quot;</span><span class="o">);</span>
        <span class="n">String</span> <span class="n">outpath</span> <span class="o">=</span> <span class="n">tmpdir</span> <span class="o">+</span> <span class="n">sep</span> <span class="o">+</span> <span class="n">filename</span><span class="o">;</span>
        <span class="n">outfile</span> <span class="o">=</span> <span class="k">new</span> <span class="n">BufferedWriter</span><span class="o">(</span><span class="k">new</span> <span class="n">FileWriter</span><span class="o">(</span><span class="n">outpath</span><span class="o">));</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">startSuite</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">Map</span> <span class="n">attrs</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span>
        <span class="n">outfile</span><span class="o">.</span><span class="na">write</span><span class="o">(</span><span class="n">name</span> <span class="o">+</span> <span class="s">&quot; &#39;&quot;</span> <span class="o">+</span> <span class="n">attrs</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;doc&quot;</span><span class="o">)</span> <span class="o">+</span> <span class="s">&quot;&#39;\n&quot;</span><span class="o">);</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">startTest</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">Map</span> <span class="n">attrs</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span>
        <span class="n">outfile</span><span class="o">.</span><span class="na">write</span><span class="o">(</span><span class="s">&quot;- &quot;</span> <span class="o">+</span> <span class="n">name</span> <span class="o">+</span> <span class="s">&quot; &#39;&quot;</span> <span class="o">+</span> <span class="n">attrs</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;doc&quot;</span><span class="o">)</span> <span class="o">+</span> <span class="s">&quot;&#39; [ &quot;</span><span class="o">);</span>
        <span class="n">List</span> <span class="n">tags</span> <span class="o">=</span> <span class="o">(</span><span class="n">List</span><span class="o">)</span><span class="n">attrs</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;tags&quot;</span><span class="o">);</span>
        <span class="k">for</span> <span class="o">(</span><span class="kt">int</span> <span class="n">i</span><span class="o">=</span><span class="mi">0</span><span class="o">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="n">tags</span><span class="o">.</span><span class="na">size</span><span class="o">();</span> <span class="n">i</span><span class="o">++)</span> <span class="o">{</span>
           <span class="n">outfile</span><span class="o">.</span><span class="na">write</span><span class="o">(</span><span class="n">tags</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="n">i</span><span class="o">)</span> <span class="o">+</span> <span class="s">&quot; &quot;</span><span class="o">);</span>
        <span class="o">}</span>
        <span class="n">outfile</span><span class="o">.</span><span class="na">write</span><span class="o">(</span><span class="s">&quot; ] :: &quot;</span><span class="o">);</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">endTest</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">Map</span> <span class="n">attrs</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span>
        <span class="n">String</span> <span class="n">status</span> <span class="o">=</span> <span class="n">attrs</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;status&quot;</span><span class="o">).</span><span class="na">toString</span><span class="o">();</span>
        <span class="k">if</span> <span class="o">(</span><span class="n">status</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="s">&quot;PASS&quot;</span><span class="o">))</span> <span class="o">{</span>
            <span class="n">outfile</span><span class="o">.</span><span class="na">write</span><span class="o">(</span><span class="s">&quot;PASS\n&quot;</span><span class="o">);</span>
        <span class="o">}</span>
        <span class="k">else</span> <span class="o">{</span>
            <span class="n">outfile</span><span class="o">.</span><span class="na">write</span><span class="o">(</span><span class="s">&quot;FAIL: &quot;</span> <span class="o">+</span> <span class="n">attrs</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;message&quot;</span><span class="o">)</span> <span class="o">+</span> <span class="s">&quot;\n&quot;</span><span class="o">);</span>
        <span class="o">}</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">endSuite</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">Map</span> <span class="n">attrs</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span>
        <span class="n">outfile</span><span class="o">.</span><span class="na">write</span><span class="o">(</span><span class="n">attrs</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;status&quot;</span><span class="o">)</span> <span class="o">+</span> <span class="s">&quot;\n&quot;</span> <span class="o">+</span> <span class="n">attrs</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;message&quot;</span><span class="o">)</span> <span class="o">+</span> <span class="s">&quot;\n&quot;</span><span class="o">);</span>
    <span class="o">}</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">close</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span>
        <span class="n">outfile</span><span class="o">.</span><span class="na">close</span><span class="o">();</span>
    <span class="o">}</span>

<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="using-internal-apis">
<h2><a class="toc-backref" href="#id534">4.4&nbsp;&nbsp;&nbsp;Using internal APIs</a></h2>
<p>Robot Framework has some public APIs which are intended to help in developing
supporting tools or extending the processing of input or output data. These
APIs are implemented as Python modules, and as such can only be used from
Python and Jython scripts and programs.</p>
<p>Unfortunately, these APIs are not particularly well documented, and
are subject to change and refinement in the future. The plan is to
enhance the documentation in the future, but before that the options for getting
more information are asking help from Robot Framework developers,
investigating existing <a class="reference internal" href="#supporting-tools">supporting tools</a> that use these APIs, or
just taking a look at the source code of Robot Framework.</p>
<div class="contents local topic" id="id220">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#executed-test-data" id="id602">4.4.1&nbsp;&nbsp;&nbsp;Executed test data</a></li>
<li><a class="reference internal" href="#id221" id="id603">4.4.2&nbsp;&nbsp;&nbsp;Test execution</a></li>
<li><a class="reference internal" href="#rebot-execution" id="id604">4.4.3&nbsp;&nbsp;&nbsp;<span class="prog">rebot</span> execution</a></li>
<li><a class="reference internal" href="#parsed-test-data" id="id605">4.4.4&nbsp;&nbsp;&nbsp;Parsed test data</a></li>
<li><a class="reference internal" href="#runnable-test-data" id="id606">4.4.5&nbsp;&nbsp;&nbsp;Runnable test data</a></li>
<li><a class="reference internal" href="#configuring-logging" id="id607">4.4.6&nbsp;&nbsp;&nbsp;Configuring logging</a></li>
</ul>
</div>
<div class="section" id="executed-test-data">
<h3><a class="toc-backref" href="#id602">4.4.1&nbsp;&nbsp;&nbsp;Executed test data</a></h3>
<p>This API consists of a factory method for reading a Robot Framework
output file into a <span class="code">TestSuite</span> object that contains all the
relevant information about the results of the test execution.
Signature of method is <span class="code">TestSuite(outpath)</span>, where
<span class="code">outpath</span> is a path to an existing output file. The returned
<span class="code">TestSuite</span> object can be used to process the results of the
test run.</p>
<p>Here is an example that reads a given output file and marks each test case whose
execution time is longer than three minutes failed. The <span class="code">TestSuite</span> object
is then serialized and normal log and report files could be generated with
<span class="prog">rebot</span>.</p>
<div class="highlight"><pre><span class="c">#!/usr/bin/env python</span>

<span class="sd">&quot;&quot;&quot;Usage: check_test_times.py inpath [outpath]</span>

<span class="sd">Reads result of a test run from Robot output file and checks that no test </span>
<span class="sd">took longer than 3 minutest to execute. If outpath is not given, the</span>
<span class="sd">result is written over the original file.</span>
<span class="sd">&quot;&quot;&quot;</span>

<span class="kn">import</span> <span class="nn">sys</span>
<span class="kn">from</span> <span class="nn">robot.output</span> <span class="kn">import</span> <span class="n">TestSuite</span>


<span class="k">def</span> <span class="nf">check_tests</span><span class="p">(</span><span class="n">inpath</span><span class="p">,</span> <span class="n">outpath</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
    <span class="k">if</span> <span class="ow">not</span> <span class="n">outpath</span><span class="p">:</span>
        <span class="n">outpath</span> <span class="o">=</span> <span class="n">inpath</span>
    <span class="n">suite</span> <span class="o">=</span> <span class="n">TestSuite</span><span class="p">(</span><span class="n">inpath</span><span class="p">)</span>
    <span class="n">_check_execution_times</span><span class="p">(</span><span class="n">suite</span><span class="p">)</span>
    <span class="n">suite</span><span class="o">.</span><span class="n">write_to_file</span><span class="p">(</span><span class="n">outpath</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">_check_execution_times</span><span class="p">(</span><span class="n">suite</span><span class="p">):</span>
    <span class="k">for</span> <span class="n">test</span> <span class="ow">in</span> <span class="n">suite</span><span class="o">.</span><span class="n">tests</span><span class="p">:</span>
        <span class="k">if</span> <span class="n">test</span><span class="o">.</span><span class="n">status</span> <span class="o">==</span> <span class="s">&#39;PASS&#39;</span> <span class="ow">and</span> <span class="n">test</span><span class="o">.</span><span class="n">elapsedtime</span> <span class="o">&gt;</span> <span class="mi">1000</span> <span class="o">*</span> <span class="mi">60</span> <span class="o">*</span> <span class="mi">3</span><span class="p">:</span>
            <span class="n">test</span><span class="o">.</span><span class="n">status</span> <span class="o">=</span> <span class="s">&#39;FAIL&#39;</span>
            <span class="n">test</span><span class="o">.</span><span class="n">message</span> <span class="o">=</span> <span class="s">&#39;Test execution time was too long: </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">test</span><span class="o">.</span><span class="n">elapsedtime</span>
    <span class="k">for</span> <span class="n">suite</span> <span class="ow">in</span> <span class="n">suite</span><span class="o">.</span><span class="n">suites</span><span class="p">:</span>
        <span class="n">_check_execution_times</span><span class="p">(</span><span class="n">suite</span><span class="p">)</span>


<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">&#39;__main__&#39;</span><span class="p">:</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="n">check_tests</span><span class="p">(</span><span class="o">*</span><span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">:])</span>
    <span class="k">except</span> <span class="ne">TypeError</span><span class="p">:</span>
        <span class="k">print</span> <span class="n">__doc__</span>
</pre></div>
</div>
<div class="section" id="id221">
<h3><a class="toc-backref" href="#id603">4.4.2&nbsp;&nbsp;&nbsp;Test execution</a></h3>
<p>This API consists of <span class="code">robot.run</span> method, which can be used for starting the
test execution. Signature of the method is <span class="code">run(*datasources, **options)</span>,
where <span class="code">datasources</span> are paths to files and directories to be executed and
<span class="code">options</span> are same as normal <a class="reference internal" href="#all-command-line-options">command line options</a> without hyphens.
Options that allow multiple values must be passed in as lists.</p>
<p>Starting from Robot Framework 2.7, the <span class="code">run</span> method allows capturing
the standard output and error streams by passing open file objects to it
as keyword arguments <cite>stdout</cite> and <cite>stderr</cite>, respectively. When the method is
executed, it returns a <a class="reference internal" href="#return-codes">return code</a> similarly as when tests are run on
the command line.</p>
<p>Example:</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">robot</span> <span class="kn">import</span> <span class="n">run</span>

<span class="n">run</span><span class="p">(</span><span class="s">&#39;path/to/tests.html&#39;</span><span class="p">,</span> <span class="n">report</span><span class="o">=</span><span class="s">&#39;custom.html&#39;</span><span class="p">,</span> <span class="n">include</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;tag1&#39;</span><span class="p">,</span> <span class="s">&#39;tag2&#39;</span><span class="p">])</span>
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s">&#39;output.txt&#39;</span><span class="p">,</span> <span class="s">&#39;w&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">output</span><span class="p">:</span>
    <span class="n">run</span><span class="p">(</span><span class="s">&#39;tests1.txt&#39;</span><span class="p">,</span> <span class="s">&#39;tests2.txt&#39;</span><span class="p">,</span> <span class="n">log</span><span class="o">=</span><span class="s">&#39;NONE&#39;</span><span class="p">,</span> <span class="n">stdout</span><span class="o">=</span><span class="n">output</span><span class="p">,</span> <span class="n">stderr</span><span class="o">=</span><span class="n">output</span><span class="p">)</span>
</pre></div>
<p>Equivalent command line usage:</p>
<pre class="literal-block">
pybot --report custom.html --include tag1 --include tag2 path/to/tests.html
pybot --log NONE tests1.txt tests2.txt 2&gt;&amp;1 &gt; output.txt
</pre>
</div>
<div class="section" id="rebot-execution">
<h3><a class="toc-backref" href="#id604">4.4.3&nbsp;&nbsp;&nbsp;<span class="prog">rebot</span> execution</a></h3>
<p>In addition to executing tests with <span class="code">robot.run</span> method, it is also
possible to execute <span class="prog">rebot</span> with <span class="code">robot.rebot</span> method. As the
example below illustrates, it has the same signature and works the same was
as <span class="code">run</span> method:</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">robot</span> <span class="kn">import</span> <span class="n">rebot</span>

<span class="n">rebot</span><span class="p">(</span><span class="s">&#39;path/to/output.xml&#39;</span><span class="p">,</span> <span class="n">report</span><span class="o">=</span><span class="s">&#39;custom.html&#39;</span><span class="p">,</span> <span class="n">include</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;tag1&#39;</span><span class="p">,</span> <span class="s">&#39;tag2&#39;</span><span class="p">])</span>
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s">&#39;stdout.txt&#39;</span><span class="p">,</span> <span class="s">&#39;w&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">stdout</span><span class="p">:</span>
    <span class="n">rebot</span><span class="p">(</span><span class="s">&#39;out1.xml&#39;</span><span class="p">,</span> <span class="s">&#39;out2.xml&#39;</span><span class="p">,</span> <span class="n">log</span><span class="o">=</span><span class="s">&#39;NONE&#39;</span><span class="p">,</span> <span class="n">stdout</span><span class="o">=</span><span class="n">stdout</span><span class="p">)</span>
</pre></div>
<p>Equivalent command line usage:</p>
<pre class="literal-block">
rebot --report custom.html --include tag1 --include tag2 path/to/output.xml
pybot --log NONE out1.xml out2.xml &gt; stdout.txt
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Prior to Robot Framework 2.7 this method was named <span class="code">run_rebot</span>.</p>
</div>
</div>
<div class="section" id="parsed-test-data">
<h3><a class="toc-backref" href="#id605">4.4.4&nbsp;&nbsp;&nbsp;Parsed test data</a></h3>
<p>Package <span class="code">robot.parsing</span> contains tools for parsing and handling test data.
<span class="code">TestCaseFile</span> and <span class="code">TestDataDirectory</span> classes can be instantiated
with named argument <span class="code">source</span> to start parsing existing test data. Example
below shows how to parse names of tests from a test file. For more details please
see the source code of Robot Framework directly.</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">robot.parsing</span> <span class="kn">import</span> <span class="n">TestCaseFile</span>

<span class="n">suite</span> <span class="o">=</span> <span class="n">TestCaseFile</span><span class="p">(</span><span class="n">source</span><span class="o">=</span><span class="s">&#39;path/to/tests.html&#39;</span><span class="p">)</span>
<span class="k">print</span> <span class="s">&#39;Suite: &#39;</span><span class="p">,</span> <span class="n">suite</span><span class="o">.</span><span class="n">name</span>
<span class="k">for</span> <span class="n">test</span> <span class="ow">in</span> <span class="n">suite</span><span class="o">.</span><span class="n">testcase_table</span><span class="p">:</span>
    <span class="k">print</span> <span class="n">test</span><span class="o">.</span><span class="n">name</span>
</pre></div>
</div>
<div class="section" id="runnable-test-data">
<h3><a class="toc-backref" href="#id606">4.4.5&nbsp;&nbsp;&nbsp;Runnable test data</a></h3>
<p>This API consists of a factory method for parsing given input files
into a runnable <span class="code">TestSuite</span> object. The signature of this
<span class="code">robot.running.TestSuite</span> method is
<span class="code">TestSuite(datasources, settings)</span>, where data sources are paths
to files and directories similarly as when executing tests from the
command line.</p>
</div>
<div class="section" id="configuring-logging">
<h3><a class="toc-backref" href="#id607">4.4.6&nbsp;&nbsp;&nbsp;Configuring logging</a></h3>
<p>Robot Framework has a global logger that is responsible for error
reporting and logging in general. This <span class="code">LOGGER</span> instance is a
proxy and it is possible to register new loggers to it. Registered
loggers get notifications when something happens and they can report
events however they want. A console logger writing warnings and errors
into the standard error stream is registered automatically but it can
be disabled. For more information about how to register loggers and
what methods loggers can implement, see the source code and
documentation of <span class="code">robot.output.LOGGER</span>.</p>
</div>
</div>
<div class="section" id="using-robot-framework-from-java">
<h2><a class="toc-backref" href="#id535">4.5&nbsp;&nbsp;&nbsp;Using Robot Framework from Java</a></h2>
<p>Starting from Robot Framework 2.5.2 Robot Framework is also distributed as a
standalone jar file that contains both Jython and Robot Framework.  This allows
<a class="reference internal" href="#starting-test-execution">command line execution</a> with only Java installed, but the jar file also
provides an API for Java usage. The current API documentation is available
<a class="reference external" href="http://code.google.com/p/robotframework/wiki/JavaIntegration">online</a>.</p>
<div class="section" id="running-tests-via-the-api">
<h3>4.5.1&nbsp;&nbsp;&nbsp;Running tests via the API</h3>
<p>The simple code below demonstrates how Robot Framework test execution can be
started from a Java program:</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">org.robotframework.RobotFramework</span><span class="o">;</span>

<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Test</span> <span class="o">{</span>

    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">runTests</span><span class="o">()</span> <span class="o">{</span>
        <span class="kt">int</span> <span class="n">rc</span> <span class="o">=</span> <span class="n">RobotFramework</span><span class="o">.</span><span class="na">run</span><span class="o">(</span><span class="k">new</span> <span class="n">String</span><span class="o">[]</span> <span class="o">{</span> <span class="s">&quot;--outputdir&quot;</span><span class="o">,</span> <span class="s">&quot;/tmp&quot;</span><span class="o">,</span> <span class="s">&quot;mytests&quot;</span> <span class="o">});</span>
        <span class="k">if</span> <span class="o">(</span><span class="n">rc</span> <span class="o">==</span> <span class="mi">0</span><span class="o">)</span>
            <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;All tests passed&quot;</span><span class="o">);</span>
        <span class="k">else</span> <span class="nf">if</span> <span class="o">(</span><span class="n">rc</span> <span class="o">&lt;=</span> <span class="mi">250</span><span class="o">)</span>
            <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">rc</span> <span class="o">+</span> <span class="s">&quot; tests failed.&quot;</span><span class="o">);</span>
        <span class="k">else</span>
            <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;Error occurred&quot;</span><span class="o">);</span>
    <span class="o">}</span>

<span class="o">}</span>
</pre></div>
<p>Return value of <span class="code">RobotFramework.run</span> has same meaning as <a class="reference internal" href="#return-codes">return code</a> of
Robot Framework execution.</p>
</div>
</div>
</div>
<div class="section" id="supporting-tools">
<h1><a class="toc-backref" href="#id282">5&nbsp;&nbsp;&nbsp;Supporting Tools</a></h1>
<div class="contents local topic" id="id224">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#library-documentation-tool-libdoc" id="id608">5.1&nbsp;&nbsp;&nbsp;Library documentation tool (<span class="prog">libdoc</span>)</a></li>
<li><a class="reference internal" href="#test-data-clean-up-tool-tidy" id="id609">5.2&nbsp;&nbsp;&nbsp;Test data clean-up tool (<span class="prog">tidy</span>)</a></li>
<li><a class="reference internal" href="#test-data-editing-tool-ride" id="id610">5.3&nbsp;&nbsp;&nbsp;Test data editing tool (RIDE)</a></li>
<li><a class="reference internal" href="#other-tools" id="id611">5.4&nbsp;&nbsp;&nbsp;Other tools</a></li>
</ul>
</div>
<div class="section" id="library-documentation-tool-libdoc">
<h2><a class="toc-backref" href="#id608">5.1&nbsp;&nbsp;&nbsp;Library documentation tool (<span class="prog">libdoc</span>)</a></h2>
<p><a class="reference external" href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> is tool for generating HTML or XML documentation from keywords of
a test library or a resource file. It is included in the source distribution
and also available through
<a class="reference external" href="http://code.google.com/p/robotframework/wiki/SupportingTools">http://code.google.com/p/robotframework/wiki/SupportingTools</a>.</p>
</div>
<div class="section" id="test-data-clean-up-tool-tidy">
<h2><a class="toc-backref" href="#id609">5.2&nbsp;&nbsp;&nbsp;Test data clean-up tool (<span class="prog">tidy</span>)</a></h2>
<p><span class="prog">tidy</span> is a tool for cleaning up and changing the format of Robot
Framework test data files. It is built-in into Robot Framework and
automatically included in the installation starting from version 2.7.</p>
<p>By default, the output of the tool is written into the standard output
stream, but it can also be redirected to a file. Alternatively, files can be
modified in-place using <span class="opt">--inplace</span> or <span class="opt">--recursive</span> options.</p>
<div class="section" id="id225">
<h3>5.2.1&nbsp;&nbsp;&nbsp;Synopsis</h3>
<pre class="literal-block">
python -m robot.tidy [options] inputfile
python -m robot.tidy [options] inputfile &gt; outputfile
python -m robot.tidy --inplace [options] inputfile [more input files]
python -m robot.tidy --recursive [options] directory
</pre>
</div>
<div class="section" id="options">
<h3>5.2.2&nbsp;&nbsp;&nbsp;Options</h3>
<blockquote>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-i</span>, <span class="option">--inplace</span></kbd></td>
<td><p class="first">Tidy given file(s) so that original file(s) are overwritten
(or removed, if the format is changed). When this option is
used, it is possible to give multiple input files. Examples:</p>
<pre class="last literal-block">
python -m robot.tidy --inplace tests.html
python -m robot.tidy --inplace --format txt *.html
</pre>
</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-r</span>, <span class="option">--recursive</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Process given directory recursively. Files in the directory
are processed in place similarly as when <span class="opt">--inplace</span>
option is used.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-f</span>, <span class="option">--format <var>&lt;txt|html|tsv&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Output file format. If omitted, the format of the input
file is used.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-p</span>, <span class="option">--use-pipes</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Use a pipe character (|) as a cell separator in the txt format.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
<td>Show this help.</td></tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="cleaning-up-the-test-data">
<h3>5.2.3&nbsp;&nbsp;&nbsp;Cleaning up the test data</h3>
<p>Test case files created with HTML editors or written by hand can be normalized
using tidy. <span class="prog">tidy</span> always writes consistent headers, consistent order for
settings, and consistent amount of whitespace between cells and tables.</p>
<p>Examples:</p>
<pre class="literal-block">
python -m robot.tidy messed_up_tests.html &gt; cleaned_tests.html
python -m robot.tidy --inplace tests.txt
</pre>
</div>
<div class="section" id="changing-the-test-data-format">
<h3>5.2.4&nbsp;&nbsp;&nbsp;Changing the test data format</h3>
<p>Robot Framework supports test data in HTML, TSV and TXT formats and <span class="prog">tidy</span>
makes changing between the formats trivial. Input format is always determined
based on the extension of the input file. Output format can be set using
the <span class="opt">--format</span> option.</p>
<p>Examples:</p>
<pre class="literal-block">
python -m robot.tidy --format tsv tests_in_html.html &gt; tests_in_tsv.tsv
python -m robot.tidy --format txt --recursive mytests
</pre>
</div>
<div class="section" id="output-encoding">
<h3>5.2.5&nbsp;&nbsp;&nbsp;Output encoding</h3>
<p>All output files are written using UTF-8 encoding. Outputs written to the
console use the current console encoding.</p>
</div>
<div class="section" id="alternative-execution">
<h3>5.2.6&nbsp;&nbsp;&nbsp;Alternative execution</h3>
<p><span class="prog">tidy</span> is used only with Python in the synopsis and examples above,
but it works also with Jython and IronPython.</p>
<p>In addition to executing <span class="prog">tidy</span> as a module (<span class="cli">python -m robot.tidy</span>),
it is possible to execute it as a script:</p>
<pre class="literal-block">
python path/robot/tidy.py [options] inputfile
</pre>
<p>This is useful if you have done a <a class="reference internal" href="#manual-installation">manual installation</a> of the framework
and just have the <span class="path">robot</span> directory with the source code somewhere
in your system.</p>
</div>
</div>
<div class="section" id="test-data-editing-tool-ride">
<h2><a class="toc-backref" href="#id610">5.3&nbsp;&nbsp;&nbsp;Test data editing tool (RIDE)</a></h2>
<p>RIDE is a standalone tool for editing test data. It helps in
creating, editing and maintaining of Robot Framework test data.
The project pages are at <a class="reference external" href="https://github.com/robotframework/RIDE/">https://github.com/robotframework/RIDE/</a>.</p>
</div>
<div class="section" id="other-tools">
<h2><a class="toc-backref" href="#id611">5.4&nbsp;&nbsp;&nbsp;Other tools</a></h2>
<div class="section" id="test-data-documentation-tool">
<h3>5.4.1&nbsp;&nbsp;&nbsp;Test data documentation tool</h3>
<p><a class="reference external" href="../../tools/testdoc/doc/testdoc.html">testdoc.py</a> is tool for generating high level documentation of a given test
suite, including the names of suites and tests as well as top-level keywords.
It is available through
<a class="reference external" href="http://code.google.com/p/robotframework/wiki/SupportingTools">http://code.google.com/p/robotframework/wiki/SupportingTools</a>.</p>
</div>
<div class="section" id="historical-reporting-tool">
<h3>5.4.2&nbsp;&nbsp;&nbsp;Historical reporting tool</h3>
<p><a class="reference external" href="../../tools/ristopy/doc/ristopy.html">risto.py</a> is a tool for generating graphs about historical statistics
of test executions. It is available through
<a class="reference external" href="http://code.google.com/p/robotframework/wiki/SupportingTools">http://code.google.com/p/robotframework/wiki/SupportingTools</a>.</p>
</div>
<div class="section" id="test-result-diffing-tool">
<h3>5.4.3&nbsp;&nbsp;&nbsp;Test result diffing tool</h3>
<p><a class="reference external" href="../../tools/robotdiff/doc/robotdiff.html">robotdiff.py</a> is a tool for generating diff reports from Robot
Framework output files. It is available through
<a class="reference external" href="http://code.google.com/p/robotframework/wiki/SupportingTools">http://code.google.com/p/robotframework/wiki/SupportingTools</a>.</p>
</div>
<div class="section" id="execution-time-reporting-tool">
<h3>5.4.4&nbsp;&nbsp;&nbsp;Execution time reporting tool</h3>
<p><a class="reference external" href="../../tools/times2csv/doc/times2csv.html">times2csv.py</a> is a tool for generating start, end and elapsed
time information about suites, tests and keywords in CSV format.
It is available through
<a class="reference external" href="http://code.google.com/p/robotframework/wiki/SupportingTools">http://code.google.com/p/robotframework/wiki/SupportingTools</a>.</p>
</div>
<div class="section" id="file-viewing-tool">
<h3>5.4.5&nbsp;&nbsp;&nbsp;File viewing tool</h3>
<p><a class="reference external" href="../../tools/fileviewer/doc/fileviewer.html">fileviewer.py</a> is a graphical tool implementing UNIX <span class="prog">tail</span> -like
functionality. It is especially designed to view <a class="reference internal" href="#debug-file">debug files</a>.
It is available through
<a class="reference external" href="http://code.google.com/p/robotframework/wiki/SupportingTools">http://code.google.com/p/robotframework/wiki/SupportingTools</a>.</p>
</div>
<div class="section" id="one-click-installer">
<h3>5.4.6&nbsp;&nbsp;&nbsp;One click installer</h3>
<p><a class="reference external" href="../../tools/oneclickinstaller/doc/oneclickinstaller.html">One click installer</a> is an <a class="reference external" href="http://www.autoitscript.com/autoit3">AutoIT</a> script that installs Robot
Framework and its dependencies.  It is available through
<a class="reference external" href="http://code.google.com/p/robotframework/wiki/SupportingTools">http://code.google.com/p/robotframework/wiki/SupportingTools</a>.</p>
</div>
<div class="section" id="test-status-checker-tool">
<h3>5.4.7&nbsp;&nbsp;&nbsp;Test status checker tool</h3>
<p><a class="reference external" href="../../tools/statuschecker/doc/statuschecker.html">statuschecker.py</a> is a tool for verifying that test case statuses
and messages and also keyword log messages are as expected.  It is available
through <a class="reference external" href="http://code.google.com/p/robotframework/wiki/SupportingTools">http://code.google.com/p/robotframework/wiki/SupportingTools</a>.</p>
</div>
<div class="section" id="manual-test-execution-tool-mabot">
<h3>5.4.8&nbsp;&nbsp;&nbsp;Manual test execution tool (mabot)</h3>
<p><span class="prog">mabot</span> is a standalone tool for reporting manual test execution
results.  It enables storing and reporting manual test cases along
with automated Robot Framework test cases. The project pages are at
<a class="reference external" href="http://code.google.com/p/robotframework-mabot/">http://code.google.com/p/robotframework-mabot/</a>.</p>
</div>
<div class="section" id="base-classes-for-java-libraries-javalibcore">
<h3>5.4.9&nbsp;&nbsp;&nbsp;Base classes for Java libraries (JavalibCore)</h3>
<p><span class="prog">JavalibCore</span> provides a collection base classes helpful in
creation of larger Java test libraries by offering several dynamic
ways of resolving available keywords at runtime. For more information,
see <a class="reference external" href="https://github.com/robotframework/JavalibCore/">https://github.com/robotframework/JavalibCore/</a>.</p>
</div>
<div class="section" id="remoteapplications">
<h3>5.4.10&nbsp;&nbsp;&nbsp;RemoteApplications</h3>
<p>RemoteApplications is a test library that enables testing applications
running on different JVM as Robot Framework, including Java Webstart
applications. For more information, see
<a class="reference external" href="https://github.com/robotframework/RemoteApplications">https://github.com/robotframework/RemoteApplications</a></p>
</div>
</div>
</div>
<div class="section" id="appendices">
<h1><a class="toc-backref" href="#id287">6&nbsp;&nbsp;&nbsp;Appendices</a></h1>
<div class="contents local topic" id="id227">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#all-available-settings-in-test-data" id="id612">6.1&nbsp;&nbsp;&nbsp;All available settings in test data</a></li>
<li><a class="reference internal" href="#all-command-line-options" id="id613">6.2&nbsp;&nbsp;&nbsp;All command line options</a></li>
<li><a class="reference internal" href="#test-data-templates" id="id614">6.3&nbsp;&nbsp;&nbsp;Test data templates</a></li>
<li><a class="reference internal" href="#documentation-formatting" id="id615">6.4&nbsp;&nbsp;&nbsp;Documentation formatting</a></li>
<li><a class="reference internal" href="#time-format" id="id616">6.5&nbsp;&nbsp;&nbsp;Time format</a></li>
</ul>
</div>
<div class="section" id="all-available-settings-in-test-data">
<h2><a class="toc-backref" href="#id612">6.1&nbsp;&nbsp;&nbsp;All available settings in test data</a></h2>
<div class="contents local topic" id="id228">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#id229" id="id617">6.1.1&nbsp;&nbsp;&nbsp;Setting table</a></li>
<li><a class="reference internal" href="#test-case-table" id="id618">6.1.2&nbsp;&nbsp;&nbsp;Test Case table</a></li>
<li><a class="reference internal" href="#id232" id="id619">6.1.3&nbsp;&nbsp;&nbsp;Keyword table</a></li>
</ul>
</div>
<div class="section" id="id229">
<h3><a class="toc-backref" href="#id617">6.1.1&nbsp;&nbsp;&nbsp;Setting table</a></h3>
<p>The Setting table is used to import test libraries, resource files and
variable files and to define metadata for test suites and test
cases. It can be included in test case files and resource files. Note
that in a resource file, a Setting table can only include settings for
importing libraries, resources, and variables.</p>
<table border="1" class="tabular docutils">
<caption>Settings available in the Setting table</caption>
<colgroup>
<col width="23%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Name</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Library</td>
<td>Used for <a class="reference internal" href="#taking-test-libraries-into-use">taking test libraries into use</a>.</td>
</tr>
<tr><td>Resource</td>
<td>Used for <a class="reference internal" href="#taking-resource-files-into-use">taking resource files into use</a>.</td>
</tr>
<tr><td>Variables</td>
<td>Used for <a class="reference internal" href="#taking-variable-files-into-use">taking variable files into use</a>.</td>
</tr>
<tr><td>Documentation</td>
<td>Used for specifying a <a class="reference internal" href="#test-suite-name-and-documentation">test suite</a> or
<a class="reference internal" href="#documenting-resource-files">resource file</a> documentation.</td>
</tr>
<tr><td>Metadata</td>
<td>Used for setting <a class="reference internal" href="#free-test-suite-metadata">free test suite metadata</a>.</td>
</tr>
<tr><td>Suite Setup</td>
<td>Used for specifying the <a class="reference internal" href="#suite-setup-and-teardown">suite setup</a>.</td>
</tr>
<tr><td>Suite Teardown</td>
<td>Used for specifying the <a class="reference internal" href="#suite-setup-and-teardown">suite teardown</a>.</td>
</tr>
<tr><td>Suite
Precondition</td>
<td>A synonym for Suite Setup.</td>
</tr>
<tr><td>Suite
Postcondition</td>
<td>A synonym for Suite Teardown.</td>
</tr>
<tr><td>Force Tags</td>
<td>Used for specifying forced values for tags when
<a class="reference internal" href="#tagging-test-cases">tagging test cases</a>.</td>
</tr>
<tr><td>Default Tags</td>
<td>Used for specifying default values for tags when
<a class="reference internal" href="#tagging-test-cases">tagging test cases</a>.</td>
</tr>
<tr><td>Test Setup</td>
<td>Used for specifying a default <a class="reference internal" href="#test-setup-and-teardown">test setup</a>.</td>
</tr>
<tr><td>Test Teardown</td>
<td>Used for specifying a default <a class="reference internal" href="#test-setup-and-teardown">test teardown</a>.</td>
</tr>
<tr><td>Test
Precondition</td>
<td>A synonym for Test Setup.</td>
</tr>
<tr><td>Test
Postcondition</td>
<td>A synonym for Test Teardown.</td>
</tr>
<tr><td>Test Template</td>
<td>Used for specifying a default <a class="reference internal" href="#test-templates">template keyword</a>
for test cases.</td>
</tr>
<tr><td>Test Timeout</td>
<td>Used for specifying a default <a class="reference internal" href="#test-case-timeout">test case timeout</a>.</td>
</tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">All setting names can optionally include a colon at the end, for
example <span class="opt">Documentation:</span>. This can make reading the settings easier
especially when using the plain text format. This is a
new feature in Robot Framework 2.5.5.</p>
</div>
</div>
<div class="section" id="test-case-table">
<h3><a class="toc-backref" href="#id618">6.1.2&nbsp;&nbsp;&nbsp;Test Case table</a></h3>
<p>The settings in the Test Case table are always specific to the test
case for which they are defined. Some of these settings override the
default values defined in the Settings table.</p>
<table border="1" class="tabular docutils">
<caption>Settings available in the Test Case table</caption>
<colgroup>
<col width="23%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Name</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>[Documentation]</td>
<td>Used for specifying a <a class="reference internal" href="#test-case-name-and-documentation">test case documentation</a>.</td>
</tr>
<tr><td>[Tags]</td>
<td>Used for <a class="reference internal" href="#tagging-test-cases">tagging test cases</a>.</td>
</tr>
<tr><td>[Setup]</td>
<td>Used for specifying a <a class="reference internal" href="#test-setup-and-teardown">test setup</a>.</td>
</tr>
<tr><td>[Teardown]</td>
<td>Used for specifying a <a class="reference internal" href="#test-setup-and-teardown">test teardown</a>.</td>
</tr>
<tr><td>[Precondition]</td>
<td>A synonym for [Setup].</td>
</tr>
<tr><td>[Postcondition]</td>
<td>A synonym for [Teardown].</td>
</tr>
<tr><td>[Template]</td>
<td>Used for specifying a <a class="reference internal" href="#test-templates">template keyword</a>.</td>
</tr>
<tr><td>[Timeout]</td>
<td>Used for specifying a <a class="reference internal" href="#test-case-timeout">test case timeout</a>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="id232">
<h3><a class="toc-backref" href="#id619">6.1.3&nbsp;&nbsp;&nbsp;Keyword table</a></h3>
<p>Settings in the Keyword table are specific to the user keyword for
which they are defined.</p>
<table border="1" class="tabular docutils">
<caption>Settings available in the Keyword table</caption>
<colgroup>
<col width="23%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Name</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>[Documentation]</td>
<td>Used for specifying a <a class="reference internal" href="#user-keyword-name-and-documentation">user keyword documentation</a>.</td>
</tr>
<tr><td>[Arguments]</td>
<td>Used for specifying <a class="reference internal" href="#user-keyword-arguments">user keyword arguments</a>.</td>
</tr>
<tr><td>[Return]</td>
<td>Used for specifying <a class="reference internal" href="#user-keyword-return-values">user keyword return values</a>.</td>
</tr>
<tr><td>[Timeout]</td>
<td>Used for specifying a <a class="reference internal" href="#user-keyword-timeout">user keyword timeout</a>.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="all-command-line-options">
<h2><a class="toc-backref" href="#id613">6.2&nbsp;&nbsp;&nbsp;All command line options</a></h2>
<p>This appendix lists all the command line options that are available
when <a class="reference internal" href="#starting-test-execution">executing test cases</a> with <span class="prog">pybot</span> or <span class="prog">jybot</span>, and when
<a class="reference internal" href="#post-processing-outputs">post-processing outputs</a> with <span class="prog">rebot</span>.</p>
<div class="contents local topic" id="id234">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#command-line-options-for-test-execution" id="id620">6.2.1&nbsp;&nbsp;&nbsp;Command line options for test execution</a></li>
<li><a class="reference internal" href="#command-line-options-for-post-processing-outputs" id="id621">6.2.2&nbsp;&nbsp;&nbsp;Command line options for post-processing outputs</a></li>
</ul>
</div>
<div class="section" id="command-line-options-for-test-execution">
<h3><a class="toc-backref" href="#id620">6.2.1&nbsp;&nbsp;&nbsp;Command line options for test execution</a></h3>
<blockquote>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-N</span>, <span class="option">--name <var>&lt;name&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-the-name">Sets the name</a> of the top-level test suite.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-D</span>, <span class="option">--doc <var>&lt;document&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-the-documentation">Sets the documentation</a> of the top-level test suite.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-M</span>, <span class="option">--metadata <var>&lt;name:value&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-free-metadata">Sets free metadata</a> for the top level test suite.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-G</span>, <span class="option">--settag <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-tags">Sets the tag(s)</a> to all executed test cases.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-t</span>, <span class="option">--test <var>&lt;name&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#by-test-suite-and-test-case-names">Selects the test cases by name</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-s</span>, <span class="option">--suite <var>&lt;name&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#by-test-suite-and-test-case-names">Selects the test suites</a> by name.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-i</span>, <span class="option">--include <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#by-tag-names">Selects the test cases</a> by tag.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-e</span>, <span class="option">--exclude <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#by-tag-names">Selects the test cases</a> by tag.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-c</span>, <span class="option">--critical <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Tests that have the given tag are <a class="reference internal" href="#setting-criticality">considered critical</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-n</span>, <span class="option">--noncritical <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Tests that have the given tag are <a class="reference internal" href="#setting-criticality">not critical</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-v</span>, <span class="option">--variable <var>&lt;name:value&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets <a class="reference internal" href="#setting-variables-in-command-line">individual variables</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-V</span>, <span class="option">--variablefile <var>&lt;path:args&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets variables using <a class="reference internal" href="#variable-files">variable files</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-d</span>, <span class="option">--outputdir <var>&lt;dir&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Defines where to <a class="reference internal" href="#output-directory">create output files</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-o</span>, <span class="option">--output <var>&lt;file&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the path to the generated <a class="reference internal" href="#output-file">output file</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-l</span>, <span class="option">--log <var>&lt;file&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the path to the generated <a class="reference internal" href="#log-file">log file</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-r</span>, <span class="option">--report <var>&lt;file&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the path to the generated <a class="reference internal" href="#report-file">report file</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-x</span>, <span class="option">--xunitfile <var>&lt;file&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the path to the generated <a class="reference internal" href="#xunit-compatible-result-file">XUnit compatible result file</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-b</span>, <span class="option">--debugfile <var>&lt;file&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>A <a class="reference internal" href="#debug-file">debug file</a> that is written during execution.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-T</span>, <span class="option">--timestampoutputs</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#timestamping-output-files">Adds a timestamp</a> to all output files.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--splitlog</span></kbd></td>
<td><a class="reference internal" href="#splitting-logs">Split log file</a> into smaller pieces that open in
browser transparently.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--logtitle <var>&lt;title&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-titles">Sets a title</a> for the generated test log.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--reporttitle <var>&lt;title&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-titles">Sets a title</a> for the generated test report.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--reportbackground <var>&lt;colors&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-background-colors">Sets background colors</a> of the generated report.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-L</span>, <span class="option">--loglevel <var>&lt;level&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-log-level">Sets the threshold level</a> for logging.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--suitestatlevel <var>&lt;level&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Defines how many <a class="reference internal" href="#configuring-displayed-suite-statistics">levels to show</a> in the
<span class="name">Statistics by Suite</span> table in outputs.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--tagstatinclude <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#including-and-excluding-tag-statistics">Includes only these tags</a> in the <span class="name">Statistics
by Tag</span> table.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--tagstatexclude <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#including-and-excluding-tag-statistics">Excludes these tags</a> from the <span class="name">Statistics
by Tag</span> table.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--tagstatcombine <var>&lt;tags:title&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Creates <a class="reference internal" href="#generating-combined-tag-statistics">combined statistics based on tags</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--tagdoc <var>&lt;pattern:doc&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Adds <a class="reference internal" href="#adding-documentation-to-tags">documentation to the specified tags</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--tagstatlink <var>&lt;pattern:link:title&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Adds <a class="reference internal" href="#creating-links-from-tag-names">external links</a> to the <span class="name">Statistics by
Tag</span> table.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--removekeywords <var>&lt;all|passed|for|wuks&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#removing-keywords-from-outputs">Removes keyword data</a> from the
generated log file.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--listener <var>&lt;name:args&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-listeners">Sets a listener</a> for monitoring test execution.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--warnonskippedfiles</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Show a warning when <a class="reference internal" href="#warning-on-invalid-files">an invalid file is skipped</a>.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--nostatusrc</span></kbd></td>
<td>Sets the <a class="reference internal" href="#return-codes">return code</a> to zero regardless of failures
in test cases. Error codes are returned normally.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--runemptysuite</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Executes tests also if the top level <a class="reference internal" href="#when-no-tests-match-selection">test suite is
empty</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--runmode <var>&lt;mode&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the execution mode for this test run.
Valid modes are <a class="reference internal" href="#exitonfailure-mode">ExitOnFailure</a>, <a class="reference internal" href="#handling-teardowns">SkipTeardownOnExit</a>,
<a class="reference internal" href="#dry-run">DryRun</a>, and <a class="reference internal" href="#randomizing-execution-order">Random</a>:&lt;what&gt;.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-W</span>, <span class="option">--monitorwidth <var>&lt;chars&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#console-width">Sets the width</a> of the console output.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-C</span>, <span class="option">--monitorcolors <var>&lt;on|off|force&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#console-colors">Specifies are colors</a> used in the console.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-P</span>, <span class="option">--pythonpath <var>&lt;path&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Additional locations where to <a class="reference internal" href="#adjusting-library-search-path">search test libraries</a> from when they are imported.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-E</span>, <span class="option">--escape <var>&lt;what:with&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#escaping-complicated-characters">Escapes characters</a> that are problematic in the console.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-A</span>, <span class="option">--argumentfile <var>&lt;path&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>A text file to <a class="reference internal" href="#argument-files">read more arguments</a> from.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
<td>Prints <a class="reference internal" href="#getting-help-and-version-information">usage instructions</a>.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--version</span></kbd></td>
<td>Prints the <a class="reference internal" href="#getting-help-and-version-information">version information</a>.</td></tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="command-line-options-for-post-processing-outputs">
<h3><a class="toc-backref" href="#id621">6.2.2&nbsp;&nbsp;&nbsp;Command line options for post-processing outputs</a></h3>
<blockquote>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-N</span>, <span class="option">--name <var>&lt;name&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-the-name">Sets the name</a> of the top level test suite.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-D</span>, <span class="option">--doc <var>&lt;document&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-the-documentation">Sets the documentation</a> of the top-level test suite.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-M</span>, <span class="option">--metadata <var>&lt;name:value&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-free-metadata">Sets free metadata</a> for the top-level test suite.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-G</span>, <span class="option">--settag <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-tags">Sets the tag(s)</a> to all processed test cases.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-t</span>, <span class="option">--test <var>&lt;name&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#by-test-suite-and-test-case-names">Selects the test cases by name</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-s</span>, <span class="option">--suite <var>&lt;name&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#by-test-suite-and-test-case-names">Selects the test suites</a> by name.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-i</span>, <span class="option">--include <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#by-tag-names">Selects the test cases</a> by tag.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-e</span>, <span class="option">--exclude <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#by-tag-names">Selects the test cases</a> by tag.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-c</span>, <span class="option">--critical <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Tests that have the given tag are <a class="reference internal" href="#setting-criticality">considered critical</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-n</span>, <span class="option">--noncritical <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Tests that have the given tag are <a class="reference internal" href="#setting-criticality">not critical</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-d</span>, <span class="option">--outputdir <var>&lt;dir&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Defines where to <a class="reference internal" href="#output-directory">create output files</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-o</span>, <span class="option">--output <var>&lt;file&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the path to the generated <a class="reference internal" href="#output-file">output file</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-l</span>, <span class="option">--log <var>&lt;file&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the path to the generated <a class="reference internal" href="#log-file">log file</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-r</span>, <span class="option">--report <var>&lt;file&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the path to the generated <a class="reference internal" href="#report-file">report file</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-x</span>, <span class="option">--xunitfile <var>&lt;file&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the path to the generated <a class="reference internal" href="#xunit-compatible-result-file">XUnit compatible result file</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-T</span>, <span class="option">--timestampoutputs</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#timestamping-output-files">Adds a timestamp</a> to all output files.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--splitlog</span></kbd></td>
<td><a class="reference internal" href="#splitting-logs">Split log file</a> into smaller pieces that open in
browser transparently.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--logtitle <var>&lt;title&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-titles">Sets a title</a> for the generated test log.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--reporttitle <var>&lt;title&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-titles">Sets a title</a> for the generated test report.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--reportbackground <var>&lt;colors&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-background-colors">Sets background colors</a> of the generated report.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-L</span>, <span class="option">--loglevel <var>&lt;level&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#setting-log-level">Sets the threshold level</a> to select log messages.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--suitestatlevel <var>&lt;level&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Defines how many <a class="reference internal" href="#configuring-displayed-suite-statistics">levels to show</a> in the
<span class="name">Statistics by Suite</span> table in outputs.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--tagstatinclude <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#including-and-excluding-tag-statistics">Includes only these tags</a> in the <span class="name">Statistics
by Tag</span> table.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--tagstatexclude <var>&lt;tag&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#including-and-excluding-tag-statistics">Excludes these tags</a> from the <span class="name">Statistics
by Tag</span> table.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--tagstatcombine <var>&lt;tags:title&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Creates <a class="reference internal" href="#generating-combined-tag-statistics">combined statistics based on tags</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--tagdoc <var>&lt;pattern:doc&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Adds <a class="reference internal" href="#adding-documentation-to-tags">documentation to the specified tags</a>.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--tagstatlink <var>&lt;pattern:link:title&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Adds <a class="reference internal" href="#creating-links-from-tag-names">external links</a> to the <span class="name">Statistics by
Tag</span> table.
table in outputs.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--removekeywords <var>&lt;all|passed|for|wuks&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#removing-keywords-from-outputs">Removes keyword data</a> from the generated outputs.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--starttime <var>&lt;timestamp&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the <a class="reference internal" href="#setting-start-and-end-time-of-execution">starting time</a> of test execution when creating
reports.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--endtime <var>&lt;timestamp&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Sets the <a class="reference internal" href="#setting-start-and-end-time-of-execution">ending time</a> of test execution when creating reports.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--nostatusrc</span></kbd></td>
<td>Sets the <a class="reference internal" href="#return-codes">return code</a> to zero regardless of failures
in test cases. Error codes are returned normally.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-E</span>, <span class="option">--escape <var>&lt;what:with&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td><a class="reference internal" href="#escaping-complicated-characters">Escapes characters</a> that are problematic in the console.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-A</span>, <span class="option">--argumentfile <var>&lt;path&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>A text file to <a class="reference internal" href="#argument-files">read more arguments</a> from.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
<td>Prints <a class="reference internal" href="#getting-help-and-version-information">usage instructions</a>.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--version</span></kbd></td>
<td>Prints the <a class="reference internal" href="#getting-help-and-version-information">version information</a>.</td></tr>
</tbody>
</table>
</blockquote>
</div>
</div>
<div class="section" id="test-data-templates">
<h2><a class="toc-backref" href="#id614">6.3&nbsp;&nbsp;&nbsp;Test data templates</a></h2>
<p>These templates can be used when <a class="reference internal" href="#creating-test-data">creating test data</a> for Robot
Framework. There are templates both for <a class="reference internal" href="#creating-test-cases">test case</a> and <a class="reference internal" href="#resource-files">resource
files</a>, and resource templates can also be used to create <a class="reference internal" href="#initialization-files">test suite
initialization files</a>. Templates are available both in <a class="reference internal" href="#supported-file-formats">HTML and TSV
format</a> and they can be customized freely.</p>
<dl class="docutils">
<dt><a class="reference external" href="../../templates/testcase_template.html">testcase_template.html</a></dt>
<dd>Test case file template in HTML format.</dd>
<dt><a class="reference external" href="../../templates/testcase_template.tsv">testcase_template.tsv</a></dt>
<dd>Test case file template in TSV format.</dd>
<dt><a class="reference external" href="../../templates/resource_template.html">resource_template.html</a></dt>
<dd>Resource file template in HTML format.</dd>
<dt><a class="reference external" href="../../templates/resource_template.tsv">resource_template.tsv</a></dt>
<dd>Resource file template in TSV format.</dd>
<dt><a class="reference external" href="../../templates/atdd_template.html">attd_template.html</a></dt>
<dd>Template for creating test cases in Acceptance Test-Driven
Development (ATDD) style. These tests are created from high-level
keywords needing no arguments, and the template has been
simplified accordingly.</dd>
</dl>
<p>Templates are available through this user guide, they are included in
the source distribution, and they can also be downloaded from
<a class="reference external" href="http://code.google.com/p/robotframework/wiki/Templates">http://code.google.com/p/robotframework/wiki/Templates</a>.</p>
</div>
<div class="section" id="documentation-formatting">
<h2><a class="toc-backref" href="#id615">6.4&nbsp;&nbsp;&nbsp;Documentation formatting</a></h2>
<p>It is possible to use simple HTML formatting with <a class="reference internal" href="#test-suite-name-and-documentation">test suite</a>,
<a class="reference internal" href="#test-case-name-and-documentation">test case</a> and <a class="reference internal" href="#user-keyword-name-and-documentation">user keyword</a> documentation in the test data, as well
as when <a class="reference internal" href="#documenting-libraries">documenting test libraries</a>.  The formatting is similar to
the style used in most wikis, and it is designed to be understandable
both as plain text and after the HTML transformation.</p>
<div class="contents local topic" id="id245">
<ul class="auto-toc simple">
<li><a class="reference internal" href="#representing-newlines" id="id622">6.4.1&nbsp;&nbsp;&nbsp;Representing newlines</a></li>
<li><a class="reference internal" href="#bold-and-italic" id="id623">6.4.2&nbsp;&nbsp;&nbsp;Bold and italic</a></li>
<li><a class="reference internal" href="#urls" id="id624">6.4.3&nbsp;&nbsp;&nbsp;URLs</a></li>
<li><a class="reference internal" href="#tables" id="id625">6.4.4&nbsp;&nbsp;&nbsp;Tables</a></li>
<li><a class="reference internal" href="#horizontal-ruler" id="id626">6.4.5&nbsp;&nbsp;&nbsp;Horizontal ruler</a></li>
</ul>
</div>
<div class="section" id="representing-newlines">
<h3><a class="toc-backref" href="#id622">6.4.1&nbsp;&nbsp;&nbsp;Representing newlines</a></h3>
<p>The documentation used for test suites, test cases and keywords is
subject to <a class="reference internal" href="#test-data-syntax">general parsing rules</a> of the test data. This means that
normal newlines are not preserved, and dividing documentation into lines
and paragraphs requires using a <a class="reference internal" href="#handling-whitespace">literal newline character sequence</a>
(<span class="code">\n</span>), as illustrated in the example below.</p>
<table class="example docutils">
  <tr>
    <th>Setting</th>
    <th>Value</th>
  </tr>
  <tr>
    <td>Documentation</td>
    <td>
      First line.\n<br>\n<br>
      Second paragraph, this time\n<br>with multiple lines.
    </td>
  </tr>
</table><p>With library documentations normal newlines are enough, and for
example the following keyword documentation would create same end result
as the above test suite documentation.</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">example_keyword</span><span class="p">():</span>
    <span class="sd">&quot;&quot;&quot;First line.</span>

<span class="sd">    Second paragraph, this time</span>
<span class="sd">    with multiple lines.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">pass</span>
</pre></div>
</div>
<div class="section" id="bold-and-italic">
<h3><a class="toc-backref" href="#id623">6.4.2&nbsp;&nbsp;&nbsp;Bold and italic</a></h3>
<p>Bold text can be created by having an asterisk before and after the
selected word or words, for example <span class="code">*this is bold*</span>. Italic
style works similarly, but the special character to use is an
underscore, for example <span class="code">_italic_</span>. It is also possible to have
bold italic with the syntax <span class="code">_*bold italic*_</span>.</p>
<p>An asterisk or an underscore alone, or in the middle of a word, does
not start formatting, but punctuation characters before or after them
are allowed. Both bold and italic are limited for formatting text on
one line, and formatting spanning several lines must be explicitly
started and stopped on every line.</p>
<table class="tabular docutils">
  <caption>Bold and italic examples</caption>
  <tr>
    <th>Unformatted</th>
    <th>Formatted</th>
  </tr>
  <tr>
    <td>*bold*</td>
    <td><b>bold</b></td>
  </tr>
  <tr>
    <td>_italic_</td>
    <td><i>italic</i></td>
  </tr>
  <tr>
    <td>*bold* and then _italic_</td>
    <td><b>bold</b> and then <i>italic</i></td>
  </tr>
  <tr>
    <td>_*bold italic*_, _italic_, nothing</td>
    <td><i><b>bold italic</b></i>, <i>italic</i>, nothing</td>
  </tr>
  <tr>
    <td>This is *bold*\n<br>*on multiple*\n<br>*lines*.</td>
    <td>This is <b>bold</b><br><b>on multiple</b><br><b>lines</b>.</td>
  </tr>
</table></div>
<div class="section" id="urls">
<h3><a class="toc-backref" href="#id624">6.4.3&nbsp;&nbsp;&nbsp;URLs</a></h3>
<p>All strings that look like URLs are automatically converted into
clickable links. Additionally, URLs that end with extension
<span class="path">.jpg</span>, <span class="path">.jpeg</span>, <span class="path">.png</span>, <span class="path">.gif</span> or
<span class="path">.bmp</span> (case-insensitive) will automatically create images. For
example URLs like <span class="code">http://some.url</span> are turned into links, and
<span class="code">http:///server/image.jpg</span> and <span class="code">file:///path/chart.png</span>
into images.</p>
<p>The automatic conversion of URLs to links is applied to all the data
in logs and reports, but creating images is done only for test suite,
test case and keyword documentation.</p>
</div>
<div class="section" id="tables">
<h3><a class="toc-backref" href="#id625">6.4.4&nbsp;&nbsp;&nbsp;Tables</a></h3>
<p>Tables are created using the pipe character with whitespace around it
as a cell boundary and the newline as a row separator. In library
documentations normal newlines are enough, but in test suite, test
case and keyword documentations the explicit newline character
sequence (<span class="code">\n</span>) is needed:</p>
<pre class="literal-block">
| *A*  | *B*   | *C*   |\n
| _1_  | Hello | world |\n
| _2_  | Hi    |       |\n
</pre>
<p>The created table always has a thin border and the text is
left-aligned. Formatting using bold and italic works also in table
cells, so it is possible to create headers. For example the above
documentation would be formatted like this:</p>
<table border="1" class="tabular docutils">
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<tbody valign="top">
<tr><td><strong>A</strong></td>
<td><strong>B</strong></td>
<td><strong>C</strong></td>
</tr>
<tr><td><em>1</em></td>
<td>Hello</td>
<td>world</td>
</tr>
<tr><td><em>2</em></td>
<td>Hi</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="horizontal-ruler">
<h3><a class="toc-backref" href="#id626">6.4.5&nbsp;&nbsp;&nbsp;Horizontal ruler</a></h3>
<p>Horizontal rulers (the &lt;hr&gt; tag) make it possible to separate larger
sections from each others, and they can be created by having three
hyphens alone in a line. With documentations in the test data literal
newlines are, again, required:</p>
<pre class="literal-block">
Some text here.\n
\n
---\n
\n
More text...
</pre>
</div>
</div>
<div class="section" id="time-format">
<h2><a class="toc-backref" href="#id616">6.5&nbsp;&nbsp;&nbsp;Time format</a></h2>
<p>Robot Framework has its own time format that is used by several
keywords (for example <span class="name">Sleep</span> and <span class="name">Wait Until Keyword
Succeeds</span>) as well as <a class="reference internal" href="#test-case-timeout">test case</a> and <a class="reference internal" href="#user-keyword-timeout">user keyword timeouts</a>. This
format is meant to be both flexible to use and easy to understand.</p>
<div class="section" id="time-as-number">
<h3>6.5.1&nbsp;&nbsp;&nbsp;Time as number</h3>
<p>The time can always be given as a plain number, in which case it is
interpreted to be seconds. Both integers and floating point numbers
work, and it is possible to use either real numbers or strings
containing numerical values. This format is useful, for example, when
the actual time value is calculated.</p>
</div>
<div class="section" id="time-as-text">
<h3>6.5.2&nbsp;&nbsp;&nbsp;Time as text</h3>
<p>Representing the time as text means using a format such as <span class="code">2 minutes
42 seconds</span>, which is normally easier to understand than just having
the value as seconds. It is, for example, not so easy to understand
how long a time <span class="code">4200</span> is in seconds, but <span class="code">1 hour 10
minutes</span> is clear immediately.</p>
<p>The basic idea of this format is having first a number and then a text
specifying what time that number represents. Numbers can be either
integers or floating point numbers, the whole format is case and space
insensitive, and the available specifier texts are:</p>
<ul class="simple">
<li>days, day, d</li>
<li>hours, hour, h</li>
<li>minutes, minute, mins, min, m</li>
<li>seconds, second, secs, sec, s</li>
<li>milliseconds, millisecond, millis, ms</li>
</ul>
<p>Examples:</p>
<pre class="literal-block">
1 min 30 secs
1.5 minutes
90 s
1 day 2 hours 3 minutes 4 seconds 5 milliseconds
1d 2h 3m 4s 5ms
</pre>
<!-- Commonly used Robot Framework related link targets -->
<!-- 1. Getting started -->
<!-- 2. Creating test data -->
<!-- 3. Executing test cases -->
<!-- 4. Extending -->
<!-- 5. Appendices -->
<!-- 6. Misc -->
<!-- External link targets -->
</div>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
<p>Generated by <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>. Syntax highlighting by <a class="reference external" href="http://pygments.org/">Pygments</a>.</p>
<p>Generated on: 2012-02-07 09:39 UTC.
</p>

</div>
</body>
</html>
